<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