0xMemory

The Missing Memory Layer for AI Agents

Stop explaining your project to every new chat session.
0xMemory transforms your repository into a self-documenting brain that evolves with your code.

Quick Start • How It Works • Features • Installation

---

🚀 Why 0xMemory?

Building complex software with AI agents is frustrating because they forget. They forget your architecture decisions, your coding conventions, and what you fixed yesterday.

0xMemory bridges the gap between simple CLI tools and complex cloud memory APIs.

Feature	☁️ Cloud Memory APIs	⌨️ CLI Agents	🧠 0xMemory
Primary Goal	App Integration	Chat Interaction	Project Intelligence
Data Privacy	❌ Third-party Servers	⚠️ Session-only	✅ 100% Local
Storage	❌ Hidden Vector DB	❌ Temp Files	✅ Markdown + Vector
Control	❌ API Access Only	❌ Re-prompting	✅ Edit Files Directly
Scope	🌍 Global / User	⏱️ Session	📂 Per-Repository
Cost	❌ Subscription	✅ Free	✅ Free (Open Source)

Most tools define memory as "storing chat logs". 0xMemory defines it as curating project knowledge.

---

🧩 How It Works

0xMemory isn't just a file writer. It's a living knowledge loop that runs legally on your machine.

flowchart LR
    subgraph IDE [Your Environment]
        Agent[🤖 AI Agent]
        User[👤 Developer]
    end

    subgraph Brain [0xMemory Brain]
        MCP[🔌 MCP Server]

        subgraph Storage [Dual Storage System]
            MD["📄 Markdown Files\n(Source of Truth)"]
            Vec["🔎 Vector DB\n(Semantic Search)"]
        end
    end

    User -->|Prompts| Agent
    Agent <-->|Read/Write| MCP
    MCP -->|Save Fact| MD
    MD -.->|Sync| Vec
    MCP -->|Search| Vec

    style Brain fill:#f0f4f8,stroke:#333,stroke-width:2px
    style Agent fill:#e1f5fe,stroke:#0277bd
    style MCP fill:#fff9c4,stroke:#fbc02d

Loading

The Knowledge Pipeline

1. Capture (The Ear)

   • Manual: You explicitly tell it: "Remember that we use Poetry for deps."
   • Auto-Extraction: You dump a raw chat log, and 0xMemory uses a local LLM (or API) to distill it into atomic facts: "Fact: Project uses Poetry. Decision: Switched from pipenv on 2024-01-15."

2. Storage (The Hippocampus)

   • Source of Truth: Everything is saved to .0xmemory/memory/*.md. These are standard Markdown files. You can edit, delete, or version control them with Git.
   • Indexing: Every save triggers a background sync to a local ChromaDB vector store. This turns text into mathematical embeddings for semantic search.

3. Recall (The Voice)

   • Hybrid Search: Use Vector Search (conceptual matches) + Keyword Search (exact matches).
   • Context Injection: When you ask "How do I install dependencies?", 0xMemory finds the relevant facts and injects them into your AI's context window before it answers.

---

✨ Features

✅ Implemented

• Project-Scoped Brains: One brain per repository. Context never leaks.
• Cross-LLM Compatible: Works with Cursor, Claude Desktop, Windsurf, and Gemini CLI.
• Hybrid Search: Combines keyword matching with semantic vector search for 100% recall.
• Human-Editable: Your memory is just brain.md and facts.md. Edit them like code.
• Knowledge Extraction: 0xmemory extract turns messy chat logs into structured facts.
• Dual Storage:
  • Read: Fast semantic search via ChromaDB.
  • Write: Durable Markdown files for version control.

🚧 Roadmap

• Git Automation: Auto-commit memory changes (feat: learned 3 new facts).
• Memory Decay: Old, unused memories fade away to keep context fresh.
• Reinforce Tool: Manually strengthen important memories.
• Context Window Control: Smartly truncate context to fit token limits.
• Session Summary: Auto-summarize chat logs into concise insights.

---

⚡ Quick Start

1. Set Up Environment

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

2. Install

pip install oxmemory

3. Initialize

Go to your project root and create a brain:

cd my-project
0xmemory init

*This creates a .0xmemory/ directory. Add .0xmemory/brain.md to your editor and describe your project high-level goals.*

4. Serve

Start the memory server:

0xmemory serve --transport http

5. Connect

For Cursor / Windsurf

Add this to your MCP config:

{
  "mcpServers": {
    "0xMemory": {
      "url": "http://localhost:8000/sse",
      "transport": "sse"
    }
  }
}

For Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "0xmemory": {
      "command": "0xmemory",
      "args": ["serve"],
      "cwd": "/absolute/path/to/your/project"
    }
  }
}

---

🛠️ Usage Patterns

The "Disciplined" Flow (Manual)

Best for keeping a clean, high-quality brain.

1. Teach: "Remember that we use black for formatting."
2. Verify: "What are our formatting rules?"
3. Correct: Open .0xmemory/memory/facts.md and edit the text directly if the AI got it wrong.

The "Lazy" Flow (Automated)

Best for fast-moving development sessions.

1. Dump: Provide a messy brain dump or paste a conversation logs.
2. Extract: Run 0xmemory extract "..."
3. Review: 0xMemory uses an LLM (Groq/Ollama) to parse out the facts for you.

---

📂 Project Structure

Your brain is transparent. Here's what's inside .0xmemory/:

File	Purpose
brain.md	The Core. High-level architecture, goals, and user context.
memory/facts.md	Technical facts (e.g., "API runs on port 8000").
memory/decisions.md	Decision logs (e.g., "Why we chose HTMX over React").
sessions/	Archived chat logs for historical retrieval.
.store/	(Git-ignored) Local ChromaDB vector index.

---

🏗️ Advanced: Token Optimization

As your memory grows, you can optimize how Cursor uses it.

Default Mode (Direct Access)

Cursor reads .0xmemory/*.md files directly into its context window.

• ✅ Fast - no tool calls needed
• ❌ Uses tokens - can fill context with large memories

Token Saver Mode

Force Cursor to use the recall tool (vector search) instead of reading files directly. This scales to unlimited memories with zero token cost until needed.

Step 1: Create .cursorignore in your project root:

.0xmemory/memory/*.md

Step 2: Copy the rules template to your project:

cp examples/cursorrules.template .cursorrules

Or create a minimal .cursorrules:

# 0xMemory Rules

You have a long-term memory system called 0xMemory.
When you need project context or past decisions, use the `recall` tool to search for it.
ALWAYS check `recall` before saying "I don't know".

📝 AI Context Templates

We provide ready-to-use context files for different AI agents. Copy these to your project root:

File	For	Usage
examples/cursorrules.template	Cursor IDE	Copy as .cursorrules
examples/CLAUDE.md	Claude Code/Desktop	Copy as CLAUDE.md
examples/GEMINI.md	Gemini CLI	Copy as GEMINI.md
examples/AGENT.md	Any AI agent	Universal template

Each template includes:

• Full tools and resources reference
• Behavior guidelines
• Customization section for your project context

---

🤝 Contributing

We are building the standard for local AI memory.

• Bugs? Open an issue.
• Ideas? Discussions are open.
• Code? PRs welcome!

_{Built for developers who want their AI to actually remember things.}