Metadata-Version: 2.4
Name: agnomem
Version: 0.2.3
Summary: Agent-agnostic memory layer — one memory store for every AI agent.
License-Expression: MIT
Project-URL: Homepage, https://github.com/milindrai/agnomem
Project-URL: Issues, https://github.com/milindrai/agnomem/issues
Keywords: memory,ai,agents,llm,openai,claude,mem0,agnostic,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.29
Requires-Dist: requests>=2.31
Requires-Dist: click>=8.1
Requires-Dist: pydantic>=2.0
Provides-Extra: server
Requires-Dist: mem0ai>=0.1; extra == "server"
Requires-Dist: chromadb>=0.5; extra == "server"
Provides-Extra: gemini
Requires-Dist: mem0ai>=0.1; extra == "gemini"
Requires-Dist: chromadb>=0.5; extra == "gemini"
Requires-Dist: google-genai>=1.0; extra == "gemini"
Dynamic: license-file

# 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.

```bash
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) | Add `http://localhost:7832/mcp` in Settings → Integrations |

---

## 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 1 — Install the package**

```bash
pip install agnomem
```

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

```bash
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
```

Add it to your `~/.zshrc` or `~/.bashrc` so it persists across sessions.

**Step 3 — Run one command**

```bash
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):

```bash
agno chatgpt-setup   # prints the exact URL and steps
```

**Verify everything is working:**

```bash
agno doctor
```

---

## Lifecycle Commands

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

```bash
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

```bash
# 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:
```bash
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
