Metadata-Version: 2.4
Name: devmemory-mcp
Version: 0.2.0
Summary: Persistent memory for AI agents via MCP
Author: Jun Zheng
License: MIT
License-File: LICENSE
Keywords: agent-memory,ai,developer-tools,mcp,rag
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: fastmcp>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: openai>=1.30
Requires-Dist: pydantic>=2.7
Requires-Dist: qdrant-client>=1.9
Requires-Dist: rich>=13.0
Requires-Dist: tiktoken>=0.7
Requires-Dist: tomli>=2.0; python_version < '3.12'
Requires-Dist: typer>=0.12
Requires-Dist: watchdog>=4.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# DevMemory

[![PyPI version](https://img.shields.io/pypi/v/devmemory)](https://pypi.org/project/devmemory/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io/)

> Persistent memory for AI agents. Every session starts where the last one ended.

## What is DevMemory?

DevMemory is a **long-term memory layer for AI coding agents**, delivered via [MCP](https://modelcontextprotocol.io/). It lets Claude Code, Cursor, Windsurf, Codex, and any MCP-compatible agent **remember decisions, lessons, and context across sessions** — so they never start from zero.

Your AI agent stores memories as it works. Next session — same agent or a different one — it recalls what matters. No copy-pasting, no re-explaining.

## The Killer Scenario

**Session 1** — Claude Code, Monday afternoon:

```
You: "Let's use Qdrant for vector storage in this project."

Agent calls memory_store:
  content: "Architecture decision: using Qdrant for vector storage.
            Reason: cloud migration path + strong Python SDK."
  memory_type: "decision"
```

**Session 2** — Cursor, Tuesday morning:

```
You: "What vector DB are we using?"

Agent calls memory_recall:
  query: "vector database choice"

→ Returns: "[DECISION] Architecture decision: using Qdrant for vector storage.
   Reason: cloud migration path + strong Python SDK.
   Project: my-app | Date: 2026-04-02"
```

Cross-agent, cross-session, zero friction.

## Quick Start

```bash
# Install
pip install devmemory

# Initialize
devmemory init

# Set up your API key (for embeddings)
export PORTKEY_API_KEY=pk-...

# Auto-configure Claude Code (one command)
devmemory setup claude-code --write

# Done. Your agent now has persistent memory.
```

For other tools:

```bash
devmemory setup cursor --write
devmemory setup windsurf --write
devmemory setup codex --write
```

## MCP Tools Reference

DevMemory exposes 6 tools via MCP that AI agents call automatically:

### Agent Memory (Tier 1)

| Tool | Description |
|------|-------------|
| `memory_store` | Store a memory — decisions, lessons, preferences, TODOs, notes. Accepts `content`, `memory_type`, `tags`, `importance`. |
| `memory_recall` | Recall relevant memories via semantic search. Filter by `project`, `memory_type`, date range. |
| `memory_forget` | Find and archive outdated memories. Preview first, then confirm to remove. |

### Project Context (Tier 2)

| Tool | Description |
|------|-------------|
| `context_get` | Get a structured summary of everything DevMemory knows about the current project. Call at session start. |
| `context_handoff` | Create a handoff note before ending a session — what was done, what's left, warnings for next session. |

### Knowledge Base (Tier 3)

| Tool | Description |
|------|-------------|
| `knowledge_search` | Search ingested documents and code. Returns raw entries with source paths and relevance scores. |

## CLI Reference

| Command | Description |
|---------|-------------|
| `devmemory init` | Initialize config and data directory |
| `devmemory memory store <content>` | Store a memory from the command line |
| `devmemory memory list` | List stored memories |
| `devmemory memory recall <query>` | Recall memories matching a query |
| `devmemory memory forget <query>` | Find and remove outdated memories |
| `devmemory context show` | Show project context summary |
| `devmemory context handoff <summary>` | Create a session handoff note |
| `devmemory setup claude-code` | Generate MCP config for Claude Code |
| `devmemory setup cursor` | Generate MCP config for Cursor |
| `devmemory setup windsurf` | Generate MCP config for Windsurf |
| `devmemory setup codex` | Generate MCP config for Codex CLI |
| `devmemory ingest <path>` | Ingest files into the knowledge base |
| `devmemory ask <query>` | Ask a question (AI-synthesized answer) |
| `devmemory search <query>` | Search the knowledge base |
| `devmemory serve` | Start the MCP server |

## How It Works

```
┌─────────────────────────────────────────────────────────┐
│                   AI Agent Layer                        │
│                                                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐ │
│  │ Claude   │  │ Cursor   │  │ Windsurf │  │ Codex  │ │
│  │ Code     │  │          │  │          │  │        │ │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └───┬────┘ │
│       └──────────────┴──────────────┴──────────────┘    │
│                          │ MCP                          │
├──────────────────────────┴──────────────────────────────┤
│                  DevMemory MCP Server                   │
│                                                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐ │
│  │  Memory     │  │  Context    │  │  Knowledge      │ │
│  │  store      │  │  get        │  │  search         │ │
│  │  recall     │  │  handoff    │  │  ingest         │ │
│  │  forget     │  │             │  │                 │ │
│  └──────┬──────┘  └──────┬──────┘  └────────┬────────┘ │
│         └────────────────┴──────────────────┘           │
│                          │                              │
├──────────────────────────┴──────────────────────────────┤
│                    Storage Layer                        │
│                                                         │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────┐  │
│  │  Qdrant     │  │  SQLite      │  │  Git-aware    │  │
│  │  (semantic  │  │  (metadata,  │  │  project      │  │
│  │   vectors)  │  │   temporal)  │  │  scoping      │  │
│  └─────────────┘  └──────────────┘  └───────────────┘  │
└─────────────────────────────────────────────────────────┘
```

All data is stored locally in `~/.devmemory/`. Memories are embedded for semantic search (Qdrant) and indexed temporally (SQLite). Projects are auto-detected from git.

## Why DevMemory?

| Without DevMemory | With DevMemory |
|---|---|
| Every AI session starts from scratch | Sessions resume where they left off |
| You re-explain decisions every time | Agent recalls past decisions automatically |
| Context lost when switching tools | Claude Code and Cursor share the same memory |
| No continuity between sessions | Handoff notes ensure nothing is forgotten |
| Manual CLAUDE.md / .cursorrules maintenance | Agent writes its own memories as it works |

## Pricing

| Tier | Price | Includes |
|------|-------|----------|
| **Free** | $0 | 3 projects, 1,000 memories, local storage |
| **Pro** | $12/mo | Unlimited projects & memories, cloud sync, cross-device |
| **Team** | $29/mo/seat | Shared team memory, permissions, onboarding |

## Documentation

- [Getting Started](docs/getting-started.md)
- [Agent Memory Guide](docs/agent-memory-guide.md)
- [MCP Integration](docs/mcp-integration.md)
- [CLI Reference](docs/cli-reference.md)

## License

MIT
