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

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 — play with asciinema play axiom-demo.cast

MCP Server

Plug Axiom into Claude Desktop, Cursor, or Windsurf in 30 seconds:

{
  "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

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

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:

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

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