axiom-memory

<p align="center"> <h1 align="center">Axiom Memory</h1> <p align="center">Autonomous memory infrastructure for AI agents.</p> <p align="center"> <a href="#-quick-start">Quick Start</a> • <a href="#-mcp-server">MCP Server</a> • <a href="#-api">API</a> • <a href="#-examples">Examples</a> • <a href="#-architecture">Architecture</a> </p> <p align="center"> <a href="https://pypi.org/project/axiom-memory/"><img src="https://img.shields.io/pypi/v/axiom-memory" alt="PyPI"></a> <a href="https://github.com/mungaibriankariuki-collab/axiom-memory"><img src="https://img.shields.io/github/stars/mungaibriankariuki-collab/axiom-memory" alt="Stars"></a> <a href="https://github.com/mungaibriankariuki-collab/axiom-memory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/mungaibriankariuki-collab/axiom-memory" alt="License"></a> </p> </p> --- **Axiom Memory** is a persistent memory system for AI agents. It stores what agents learn, retrieves it across sessions, and is built to evolve autonomously. Works offline. Zero API keys required by default. MCP server included. ``` pip install axiom-memory ``` --- ## Demo ```python from axiom import MemoryStore store = MemoryStore() # Store a memory store.remember("Brian prefers dark mode", tags=["preference", "user-brian"]) # Search later results = store.search("dark mode", limit=5) # See what you know print(store.stats()) # → Total: 42 memories, Avg importance: 0.67 ``` ### CLI Demo ``` $ axiom chat Axiom Chat — I remember everything you tell me. Type 'exit' to quit, 'stats' for memory stats. You> I'm Brian, I'm building an AI startup in Nairobi → Remembered (id=f5db1eff, importance=0.55) You> I love Python and dark mode → Remembered (id=878939c2, importance=0.55) You> stats Total memories: 8 Avg importance: 0.550 You> exit Goodbye! $ axiom chat Welcome back! I remember 8 things about you. You> What do you know about me? → Remembered (id=a1b2c3d4, importance=0.66) 💡 Related: Brian prefers dark mode ``` > Full terminal recording: [`axiom-demo.cast`](axiom-demo.cast) — play with `asciinema play axiom-demo.cast` ## MCP Server Plug Axiom into Claude Desktop, Cursor, or Windsurf in 30 seconds: ```json { "mcpServers": { "axiom-memory": { "command": "axiom", "args": ["serve", "--port", "8765"] } } } ``` Your AI assistant now has permanent memory. Every session reads and writes to the same store. ## CLI ```bash axiom remember "Brian likes Python" --tags preference,user-brian axiom search "Python" axiom stats axiom chat # Interactive persistent chatbot axiom export backup.json axiom import backup.json axiom serve # Start MCP server ``` ## API ```python from axiom import MemoryStore store = MemoryStore("memories.db") # Core operations store.remember("content", tags=["tag"], importance=0.8) store.recall("memory-id") store.search("query", limit=10, tags=["python"], min_importance=0.5) store.update("memory-id", content="new content", importance=0.95) store.forget("memory-id") store.stats() # Import / Export store.export_json("backup.json") store.import_json("backup.json") # LLM-powered extraction (requires OpenAI key) store.extract_from_conversation("I love building AI agents in Python") ``` ## Features | Feature | Status | Description | |---------|--------|-------------| | SQLite storage | ✅ | Persistent, fast, FTS5 full-text search | | Keyword search | ✅ | Tag/importance filtering, pagination | | Importance scoring | ✅ | Recency + usage + explicit hints | | JSON import/export | ✅ | Portable, backup-friendly | | CLI tool | ✅ | Full CRUD + chat + serve | | MCP server | ✅ | Claude Desktop, Cursor, Windsurf | | LLM extraction | ✅ | Auto-extract memories from conversations | | Dream Engine | 🔲 | Consolidation, forgetting, compression (interface ready) | | Semantic search | 🔲 | Via sentence-transformers (`pip install axiom-memory[semantic]`) | | Vector DB backends | 🔲 | PostgreSQL, Redis, Pinecone (interface ready) | ## Architecture ``` axiom/ ├── core/ │ ├── memory.py # Memory model (Pydantic) │ ├── store.py # MemoryStore — main API │ ├── storage/ # Pluggable storage backends │ │ ├── base.py # StorageBackend ABC │ │ └── sqlite.py # SQLite implementation │ ├── search/ # Pluggable search engines │ │ ├── base.py # SearchEngine ABC │ │ └── keyword.py # FTS5 keyword search │ ├── scoring/ # Pluggable scoring engines │ │ ├── base.py # ScoringEngine ABC │ │ └── simple.py # Recency + usage + importance │ └── dream.py # DreamEngine interface (future) ├── llm/extractor.py # Optional LLM extraction ├── mcp/server.py # MCP server ├── cli.py # CLI tool ├── io.py # JSON import/export └── config.py # Settings ``` ### Extending Add a custom storage backend: ```python from axiom.core.storage.base import StorageBackend class MyStorage(StorageBackend): def store(self, memory): ... def retrieve(self, memory_id): ... def update(self, memory): ... def delete(self, memory_id): ... def search(self, query, limit, offset): ... def list_all(self, limit, offset): ... def count(self): ... def count_by_type(self): ... def all_tags(self): ... def increment_usage(self, memory_id): ... def get_all(self): ... store = MemoryStore(storage=MyStorage()) ``` ## Requirements - Python 3.12+ - SQLite (built into Python) Optional: OpenAI API key for LLM extraction. ## Development ```bash git clone https://github.com/mungaibriankariuki-collab/axiom-memory cd axiom-memory python -m venv .venv && source .venv/bin/activate pip install -e ".[dev]" pre-commit install pytest --cov=axiom ``` ## License MIT