Skip to content

Commit bb57cf9

Browse files
Andreasclaude
Andreas
and
claude
committed
docs: polished README with architecture, examples, and GitHub metadata
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent cecc446 commit bb57cf9

File tree

2 files changed

+190
-39
lines changed

2 files changed

+190
-39
lines changed

‎.github/FUNDING.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
github: CytrexSGR

‎README.md‎

Lines changed: 189 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,49 @@
1-
# persistent-agent-memory
2-
3-
MCP server that gives AI agents persistent semantic memory across sessions.
1+
<p align="center">
2+
<h1 align="center">persistent-agent-memory</h1>
3+
<p align="center">
4+
MCP server that gives AI agents persistent semantic memory across sessions.
5+
</p>
6+
<p align="center">
7+
<a href="#quick-start">Quick Start</a> &bull;
8+
<a href="#mcp-tools">Tools</a> &bull;
9+
<a href="#configuration">Config</a> &bull;
10+
<a href="#skills">Skills</a> &bull;
11+
<a href="#architecture">Architecture</a>
12+
</p>
13+
</p>
14+
15+
---
16+
17+
**The problem:** Claude Code, Cursor, Windsurf, and other MCP-based agents forget everything between sessions. Every conversation starts from zero.
18+
19+
**The fix:** A single MCP server that stores memories as embeddings, recalls them via natural language, and orchestrates session handoffs -- so your agent picks up where it left off.
420

521
## Features
622

7-
- **11 MCP tools** -- remember, recall, forget, typed decisions/rules, bootstrap context, directory indexing
8-
- **Semantic search** -- memories are embedded and recalled via natural language
9-
- **Session continuity** -- handoff + bootstrap skills for structured session transitions
10-
- **Pluggable storage** -- SQLite + sqlite-vec (default, zero-dependency) or PostgreSQL + pgvector
11-
- **Pluggable embeddings** -- any OpenAI-compatible API (Ollama, vLLM, OpenAI) or local sentence-transformers
12-
- **Directory indexer** -- semantic search over Markdown files / Obsidian vaults
23+
| | |
24+
|---|---|
25+
| **11 MCP tools** | remember, recall, forget, typed decisions/rules, bootstrap context, directory indexing |
26+
| **Semantic search** | Memories are embedded and recalled via natural language -- not keyword matching |
27+
| **Session continuity** | Handoff + bootstrap skills for structured session transitions |
28+
| **Pluggable storage** | SQLite + sqlite-vec (default, zero-dependency) or PostgreSQL + pgvector |
29+
| **Pluggable embeddings** | Any OpenAI-compatible API (Ollama, vLLM, OpenAI) or local sentence-transformers |
30+
| **Directory indexer** | Semantic search over Markdown files and Obsidian vaults |
31+
| **Multi-agent ready** | Source agent tracking, typed handoffs between agents and sessions |
1332

1433
## Quick Start
1534

1635
```bash
1736
# Install
1837
pip install persistent-agent-memory
1938

20-
# Start with Ollama for local embeddings (free, no API key)
39+
# Start with Ollama for local embeddings (free, no API key needed)
2140
ollama pull nomic-embed-text
2241
pam serve --stdio
2342
```
2443

25-
### Claude Code Integration
44+
### Claude Code
2645

27-
Add to your `.mcp.json`:
46+
Add to your project's `.mcp.json`:
2847

2948
```json
3049
{
@@ -35,50 +54,175 @@ Add to your `.mcp.json`:
3554
}
3655
```
3756

38-
### With Docker (PostgreSQL backend)
57+
That's it. Your agent now has persistent memory across all sessions.
58+
59+
### Other MCP Clients
60+
61+
Any MCP-compatible client (Cursor, Windsurf, custom agents) can connect via stdio or SSE:
3962

4063
```bash
41-
docker compose up -d
42-
```
64+
# stdio (for direct integration)
65+
pam serve --stdio
4366

44-
## Configuration
67+
# SSE (for network access)
68+
pam serve # defaults to 0.0.0.0:8765
69+
```
4570

46-
Copy `.env.example` to `.env` and adjust:
71+
### Docker (PostgreSQL backend)
4772

48-
| Variable | Default | Description |
49-
|----------|---------|-------------|
50-
| `STORAGE_BACKEND` | `sqlite` | `sqlite` or `postgres` |
51-
| `SQLITE_PATH` | `./data/memory.db` | Path to SQLite database |
52-
| `DATABASE_URL` | -- | PostgreSQL connection string |
53-
| `EMBEDDING_PROVIDER` | `api` | `api` or `local` |
54-
| `EMBEDDING_API_URL` | `http://localhost:11434/v1` | OpenAI-compatible embedding endpoint |
55-
| `EMBEDDING_MODEL` | `nomic-embed-text` | Embedding model name |
56-
| `EMBEDDING_DIMENSIONS` | `768` | Vector dimensions |
57-
| `BOOTSTRAP_CACHE_TTL` | `3600` | Bootstrap context cache (seconds) |
73+
```bash
74+
docker compose up -d
75+
```
5876

5977
## MCP Tools
6078

79+
### Core Memory
80+
6181
| Tool | Description |
6282
|------|-------------|
63-
| `remember` | Store a memory with content, category, tags, importance |
83+
| `remember` | Store a memory with content, category, tags, importance (1-5) |
6484
| `recall` | Semantic search via natural language query |
6585
| `forget` | Delete a memory by ID |
6686
| `remember_decision` | Store an architecture decision with context + rationale |
67-
| `remember_rule` | Store a rule/constraint |
68-
| `search_knowledge` | Extended search with threshold and filters |
69-
| `get_context` | Load context for a topic |
70-
| `get_session_summary` | Last N memories as briefing |
71-
| `get_bootstrap_context` | Everything needed at session start (cached) |
72-
| `index_directory` | Scan .md files, chunk, embed, store |
87+
| `remember_rule` | Store a rule/constraint that must be followed |
88+
89+
### Context & Search
90+
91+
| Tool | Description |
92+
|------|-------------|
93+
| `search_knowledge` | Extended search with threshold, filters, and time range |
94+
| `get_context` | Load all relevant context for a topic |
95+
| `get_session_summary` | Last N memories as a session briefing |
96+
| `get_bootstrap_context` | Everything needed at session start (cached 1h) |
97+
98+
### Directory Indexer
99+
100+
| Tool | Description |
101+
|------|-------------|
102+
| `index_directory` | Scan .md files, chunk by heading, embed, store |
73103
| `search_indexed` | Semantic search over indexed files |
74104

105+
The indexer chunks Markdown files by heading, tracks file modification times, and only re-indexes changed files.
106+
107+
## Architecture
108+
109+
```
110+
┌─────────────────────────────────────────────────────────┐
111+
│ MCP Client │
112+
│ (Claude Code, Cursor, custom) │
113+
└───────────────────────┬─────────────────────────────────┘
114+
│ stdio / SSE
115+
┌───────────────────────▼─────────────────────────────────┐
116+
│ persistent-agent-memory │
117+
│ │
118+
│ ┌──────────┐ ┌──────────────┐ ┌──────────────────┐ │
119+
│ │ 11 MCP │ │ Embedding │ │ Storage │ │
120+
│ │ Tools │ │ Provider │ │ Backend │ │
121+
│ │ │ │ │ │ │ │
122+
│ │ remember │ │ OpenAI-compat│ │ SQLite + vec │ │
123+
│ │ recall │ │ (default) │ │ (default) │ │
124+
│ │ forget │ │ OR │ │ OR │ │
125+
│ │ decide │ │ sentence- │ │ PostgreSQL + │ │
126+
│ │ rule │ │ transformers │ │ pgvector │ │
127+
│ │ search │ │ │ │ │ │
128+
│ │ context │ └──────────────┘ └──────────────────┘ │
129+
│ │ summary │ │
130+
│ │ bootstrap│ ┌──────────────┐ │
131+
│ │ index │ │ Directory │ │
132+
│ │ search_ix│ │ Indexer │ │
133+
│ └──────────┘ └──────────────┘ │
134+
└─────────────────────────────────────────────────────────┘
135+
```
136+
137+
### Memory Model
138+
139+
```
140+
Memory {
141+
id: UUID
142+
content: text
143+
embedding: vector # semantic search
144+
category: enum # general | decision | rule | context | handoff | project
145+
tags: string[] # free-form filtering
146+
importance: 1-5 # prioritization
147+
source_agent: string # who wrote this
148+
created_at / updated_at
149+
metadata: json # extensible
150+
}
151+
```
152+
153+
**Category semantics:**
154+
- `decision` -- prioritized in bootstrap context
155+
- `rule` -- always loaded when topic matches
156+
- `handoff` -- searched at session start for pending work
157+
- `project` -- grouped by project tag
158+
159+
## Configuration
160+
161+
Copy `.env.example` to `.env`:
162+
163+
```bash
164+
# Storage (pick one)
165+
STORAGE_BACKEND=sqlite # sqlite | postgres
166+
SQLITE_PATH=./data/memory.db
167+
# DATABASE_URL=postgresql://... # only for postgres
168+
169+
# Embeddings (pick one)
170+
EMBEDDING_PROVIDER=api # api | local
171+
EMBEDDING_API_URL=http://localhost:11434/v1
172+
EMBEDDING_MODEL=nomic-embed-text
173+
EMBEDDING_DIMENSIONS=768
174+
# EMBEDDING_API_KEY=sk-... # only for cloud APIs
175+
176+
# Server
177+
HOST=0.0.0.0
178+
PORT=8765
179+
BOOTSTRAP_CACHE_TTL=3600
180+
```
181+
182+
### Embedding Providers
183+
184+
| Provider | Config | Best for |
185+
|----------|--------|----------|
186+
| **Ollama** (default) | `EMBEDDING_API_URL=http://localhost:11434/v1` | Local, free, no API key |
187+
| **OpenAI** | `EMBEDDING_API_URL=https://api.openai.com/v1` + API key | Quality, hosted |
188+
| **vLLM / LM Studio** | Any `/v1/embeddings` endpoint | Self-hosted GPU |
189+
| **sentence-transformers** | `EMBEDDING_PROVIDER=local` | Direct GPU, no server |
190+
75191
## Skills
76192

77-
Install skills to your agent's skills directory for integration:
193+
Skills are structured prompts that orchestrate tool usage. Install to your agent's skills directory:
78194

79-
- **session-handoff** -- structured handoff at session end
80-
- **memory-bootstrap** -- session start protocol (loads context + pending handoffs)
81-
- **atlas-update** (optional) -- infrastructure documentation updates
195+
### session-handoff
196+
197+
Structured handoff at session end:
198+
199+
```
200+
SESSION-HANDOFF 2025-01-15
201+
FROM: agent-a on desktop
202+
PROJECT: auth-rewrite
203+
STATUS: IN_PROGRESS
204+
205+
DONE:
206+
- Implemented OAuth2 flow (commit abc123)
207+
208+
OPEN:
209+
- Token refresh logic (P1)
210+
211+
ENTRY:
212+
recall("auth-rewrite session-handoff")
213+
```
214+
215+
### memory-bootstrap
216+
217+
Session start protocol:
218+
1. Detect environment (hostname, IP, working directory)
219+
2. `get_bootstrap_context()` -- loads decisions, rules, handoffs
220+
3. `recall("session-handoff IN_PROGRESS OR BLOCKED")` -- find pending work
221+
4. Summarize to user
222+
223+
### atlas-update (optional)
224+
225+
Infrastructure documentation pattern for multi-server setups.
82226

83227
## Development
84228

@@ -90,6 +234,12 @@ pip install -e ".[dev]"
90234
pytest
91235
```
92236

237+
**50 tests**, covering config, models, embeddings, storage, service, indexer, and all MCP tools.
238+
239+
Optional test dependencies:
240+
- `pip install -e ".[local]"` -- sentence-transformers tests
241+
- `TEST_DATABASE_URL=postgresql://... pytest` -- PostgreSQL tests
242+
93243
## License
94244

95-
AGPL-3.0-or-later. Commercial license available -- contact for details.
245+
AGPL-3.0-or-later with commercial dual-licensing. For proprietary use without AGPL obligations, contact for a commercial license.

0 commit comments

Comments
 (0)