MemSpire 🏛️

A lightweight, vertical, hierarchical memory system for local AI agents, especially on mobile devices (Termux, etc.).

Forget flat vector stores or bloated databases. MemSpire gives your agent a structured "memory palace" — inspired by the method of loci, but built for code and SQLite.

The Structure

• Wing — High-level domain (e.g., Identity, Projects, World)
• Floor — Category inside the wing (e.g., Family, Coding, Hobbies)
• Cell — Individual fact or memory, timestamped and queryable

This hierarchy keeps things organized and searchable without turning your memory into a messy keyword soup.

Quick Start

pip install git+https://github.com/TheOneTrueNiz/memspire.git

from memspire import MemSpire

# Single-file SQLite backend
spire = MemSpire("my_memory.db")

# Store a fact
spire.add_fact(
    wing="World",
    floor="Maya",
    fact="Has gymnastics practice every Wednesday at 5 PM"
)

# Recall it later
results = spire.recall("gymnastics")
for wing, floor, fact, timestamp in results:
    print(f"[{wing} > {floor}] {fact} ({timestamp})")
    
    Features

SQLite-powered — one portable .db file. Commit it, copy it, sync it however you want.
Hierarchical by design — stops the flat-list chaos that plagues most agent memory.
Mobile-first — tiny footprint, zero heavy deps, runs great in Termux.
Simple API — add, recall, (presumably delete/update coming).
Local only — your agent's memory stays on-device. No cloud, no API keys, no surveillance.

Why This Exists
Most AI agent memory solutions are either:

Dumb key-value blobs that forget context
Over-engineered vector DBs that eat battery and storage
Cloud-dependent (and suddenly your agent is phoning home)

MemSpire is the middle path: structured enough to be useful, simple enough to run anywhere your Python does.
Roadmap / Missing Pieces (being honest with you)

Delete / update facts
Better search (semantic? fuzzy? both?)
Export / import tools
Examples with actual local LLMs (Ollama, etc.)

Pull requests welcome if you want to help fill these in.
License
MIT — do whatever you want with it.