agnomem 0.2.4

Agent-agnostic memory layer — one memory store for every AI agent.

agnomem

Agent-agnostic memory layer — one memory store for every AI agent.

Claude forgets everything when you close the tab. Cursor knows nothing about what you told ChatGPT. Every AI tool starts from zero, every single session. You end up being the only "memory" in your own setup — repeating your preferences, your project context, your decisions, over and over.

agnomem fixes this. A single local memory server that every AI tool reads from and writes to automatically, through the standard MCP protocol. Install once, works everywhere.

pip install agnomem
export GOOGLE_API_KEY=...   # or OPENAI_API_KEY or ANTHROPIC_API_KEY
agno install

That's it. Claude Desktop, Cursor, Windsurf, Antigravity, and ChatGPT Desktop now share the same memory — across sessions, across tools, across accounts.

---

Supported AI Tools

Tool	Integration	How
Claude Desktop	Auto	MCP registered in ~/.claude/claude.json
Cursor	Auto	MCP registered in ~/.cursor/mcp.json
Windsurf	Auto	MCP registered in ~/.codeium/windsurf/mcp_config.json
Antigravity (Google)	Auto	MCP registered in ~/.gemini/antigravity/mcp_config.json
ChatGPT Desktop	Manual (once) · Plus only	Add http://localhost:7832/mcp in Settings → Integrations (requires ChatGPT Plus)

---

How It Works

Claude Desktop / Cursor / Windsurf / Antigravity / ChatGPT Desktop
                          │
                          │  MCP (Model Context Protocol)
                          │  search_memory / save_memory / delete_memory
                          ▼
              agnomem server  (localhost:7832)
                          │
                          ▼
              mem0  ──  ChromaDB  ──  ~/.agnomem/
              (fact      (vector       (your data,
             extraction)  search)      stays local)

When you open any supported AI tool:

1. The tool reads its MCP config and spawns agno mcp automatically
2. agnomem registers 3 native tools: search_memory, save_memory, delete_memory
3. Before every task the AI searches your memory for relevant context
4. After you confirm something new the AI saves it to memory
5. Next session — same tool or different tool — it already knows

---

Quick Start

Step 0 — Make sure Python is installed

# Check if Python is already installed
python3 --version

If you get command not found, install Python first:

# Mac — easiest via Homebrew
brew install python3

# Or download the installer from:
# https://www.python.org/downloads/

Step 1 — Install the package

pip install agnomem

If you get agno: command not found when running step 3, use this instead: python3 -m agnomem install

Step 2 — Set an API key (one of these, whichever you already have)

export GOOGLE_API_KEY=your_key_here      # Google Gemini — free tier available
export OPENAI_API_KEY=your_key_here      # OpenAI
export ANTHROPIC_API_KEY=your_key_here   # Anthropic

Step 3 — Run one command

agno install

That's it. This automatically installs the remaining dependencies, starts the memory server, registers MCP in Claude Desktop / Cursor / Windsurf / Antigravity, and sets up auto-start so the server runs on every login — no maintenance needed.

ChatGPT Desktop requires one extra manual step (HTTP-based MCP can't be auto-configured):

agno chatgpt-setup   # prints the exact URL and steps

Verify everything is working:

agno doctor

---

Lifecycle Commands

These four commands cover everything you'll ever need after the initial install:

agno install       # one-time setup — install, start, inject, auto-start
agno deactivate    # turn off — stops server, removes MCP from all tools, removes auto-start
                   #            your memories are kept safe on disk
agno activate      # turn back on — starts server, re-registers MCP, reinstalls auto-start
agno reset         # wipe memories — clears the entire memory store, server keeps running
agno uninstall     # full removal — removes everything (prompts you about memory deletion)

The mental model:

Scenario	Command
First time using agnomem	agno install
Temporarily turn off (keep memories)	agno deactivate
Turn back on after deactivating	agno activate
Start completely fresh	agno reset
Remove agnomem from your system	agno uninstall

---

CLI Reference

# Lifecycle (main commands)
agno install                      # full one-time setup
agno deactivate                   # turn off (keeps memories, reversible)
agno activate                     # turn back on after deactivate
agno reset                        # wipe all memories (server stays on)
agno reset --user alice           # wipe one user's memories only
agno uninstall                    # full nuclear removal

# Auto-start service (macOS launchd)
agno service install              # server auto-starts on every login
agno service uninstall            # remove auto-start
agno service status               # check if service is installed and running

# Server (advanced / debug)
agno start                        # start memory server manually
agno stop                         # stop memory server
agno status                       # show server status + pid
agno logs                         # show server logs
agno logs -f                      # follow logs (tail -f)

# MCP registration (advanced / debug)
agno inject                       # register MCP in all AI tools
agno eject                        # remove MCP from all AI tools
agno chatgpt-setup                # ChatGPT Desktop setup instructions

# Memory
agno search "deploy preferences"  # semantic search
agno remember "use fly deploy"    # save a memory
agno list                         # list all memories
agno list --json                  # raw JSON output
agno forget <id>                  # delete one memory by ID

# Backup & Migration
agno export -o backup.json        # export all memories to file
agno import backup.json           # import memories from file

# Health
agno doctor                       # full health check

---

LLM Provider Selection

agnomem auto-detects which API key you have and configures accordingly:

API Key	LLM	Embedder
GOOGLE_API_KEY	Gemini 2.5 Flash	gemini-embedding-001 (768d)
OPENAI_API_KEY	GPT-4o-mini	text-embedding-3-small (1536d)
ANTHROPIC_API_KEY	Claude Haiku	HuggingFace (local)

Override the model:

export AGNOMEM_LLM_MODEL=gemini-2.5-pro   # use a different model
agno start

---

Architecture

~/.agnomem/
├── chroma/          ← ChromaDB vector store (all your memories)
└── config.json      ← port, user_id settings

~/.claude/claude.json                 ← Claude Desktop MCP registration
~/.cursor/mcp.json                    ← Cursor MCP registration
~/.codeium/windsurf/mcp_config.json   ← Windsurf MCP registration
~/.gemini/antigravity/mcp_config.json ← Antigravity MCP registration

Memory pipeline (on save):

Raw text → Gemini/GPT/Claude (fact extraction) → clean fact → embedding vector → ChromaDB

Search pipeline:

Query → embedding vector → ChromaDB cosine similarity → top-k memories → AI tool

All data stays on your machine. The only external calls are to your LLM provider for fact extraction and embedding — the same calls you already make to use that provider.

---

Requirements

• Python 3.10+
• One of: GOOGLE_API_KEY, OPENAI_API_KEY, or ANTHROPIC_API_KEY
• macOS / Linux (Windows support coming)

---

License

MIT