pamiec

Persistent, queryable memory for Claude Code. Builds a knowledge graph of the people, projects, companies, and decisions you discuss across sessions, so Claude doesn't forget who you are or what you're working on the next time you open a terminal.

Inspired by GAM (Graph Attention Memory, arxiv 2604.12285).

---

What you get

When you start a Claude Code session and ask anything that touches an entity already in your memory — a project, a person, a grant, a decision — Claude calls recall_context and gets back the relevant graph slice automatically. You don't tell Claude what to remember, and you don't tell it when to recall.

Three layers feed the recall:

• Entities — stable long-term facts. "Alice founded Acme, based in Berlin." "ProjectX is an internal tool for ingesting customer data."
• Past episodes — date-stamped summaries of past conversations, queryable directly. "What did we discuss about grants last Tuesday?"
• Live (current session) — turn-by-turn capture of the in-progress session, available within ~2 minutes. "What did the user just say about pricing?"

A web visualization (pamiec graph) shows the whole graph as a force-directed network — entities as colored circles, episodes as grey squares, edges as typed arrows.

---

Setup

1. Install

pamiec is a Python project with a CLI and an MCP server.

cd ~/pamiec
uv sync                    # or pip install -e .
pamiec init              # creates the SQLite DB and pre-loads the embedding model

The first init downloads BAAI/bge-small-en-v1.5 (~130 MB) for local embeddings. After that, no network calls except to Claude Haiku for extraction.

2. Register the MCP server

claude mcp add --scope user pamiec "$HOME/pamiec/.venv/bin/pamiec-mcp"

This makes recall_context and remember available as tools in every Claude Code session. Verify:

claude mcp list
# pamiec: /home/.../pamiec-mcp  - ✓ Connected

3. Add the cron jobs

crontab -e

Append:

*/2  * * * * $HOME/pamiec/.venv/bin/pamiec capture              >> $HOME/.pamiec/cron.log 2>&1
*/30 * * * * $HOME/pamiec/.venv/bin/pamiec consolidate-session  >> $HOME/.pamiec/cron.log 2>&1

That's it. The system runs in the background.

---

What runs when

Job	Cadence	Cost	What it does
pamiec capture	every 2 min	~0.5 s, no LLM	Embeds new conversation turns and writes them to a live buffer (Tier 1).
pamiec consolidate-session	every 30 min	one Haiku call per ~8 KB of transcript per segment	Drains the live buffer, detects topic boundaries, promotes each segment to a stored episode + extracts entity facts.

You can also run either manually any time.

---

How Claude uses it (no manual action)

In a Claude Code session, when you mention any project, person, decision, or ask a question that has prior history, Claude will call recall_context and prepend the result. You'll see something like:

## Entities

# Alice
- founder of Acme
- based in Berlin
- background in distributed systems

# ProjectX
- internal tool for customer data ingestion
- written in Python, deployed to Kubernetes
- depends on the legacy auth service

## Past episodes

[episode 2026-01-14] Discussed the migration plan for ProjectX, identified two
blockers around schema versioning…

## Live (current session)

[live 13:15] User: should we proceed with the migration this week?

Claude only calls recall when it's relevant — you don't trigger it. If a conversation is about something the graph has nothing on, recall returns nothing and Claude proceeds normally.

---

Manual operations

Force a recall (for inspection)

pamiec recall "grants and funding options"

Returns exactly what Claude would see for that query.

Add a fact mid-session

pamiec remember "Bob from Acme will join the migration review on Friday"

The text is treated as a one-turn micro-conversation and processed through the same extraction pipeline (Haiku call + entity merging). Use this only for things that won't appear naturally in the conversation transcript.

Inspect episodes

pamiec episodes                     # list all
pamiec episodes dfcef718            # detail of one episode (id prefix)

Detail view shows the summary, every linked entity, and every turn with timestamps.

Visualize the graph

pamiec graph

Opens a browser tab with the force-directed graph. Drag nodes to rearrange, scroll to zoom, click any node for full detail in a side panel. Episodes render as grey squares connected by dashed lines to the entities they mention. Hover an edge to see its relationship type.

Compact bloated entities

pamiec compact

When a single entity has accumulated too many redundant facts across many sessions, compaction runs a single Haiku call to merge overlapping facts and remove session-narrative noise. Triggered automatically during consolidation, but you can run it manually too.

Status

pamiec status

Counts and last-run timestamps.

---

What gets remembered, and what doesn't

pamiec extracts:

• Specific named people (Alice, Bob)
• Named projects, products, codebases (ProjectX, internal-cli)
• Companies and institutions (Acme, the central university)
• Published works (papers by title or DOI)
• Named grants or programs (an EU funding call)
• Concrete tools or technologies discussed as entities

It deliberately ignores:

• Concepts being discussed or designed ("memory gap", "consolidation flow")
• Generic technical topics ("graph visualization", "knowledge graph")
• Problems being solved or critiques ("hallucinated edges", "noisy nodes")
• Architecture decisions or approaches ("three-tier architecture")
• Anything that wouldn't exist in the world outside the conversation

Every extracted entity and edge has a confidence score. Anything below 0.7 is dropped before it touches the graph.

---

Trust but verify

The graph is your memory, not a source of truth. If something is wrong:

sqlite3 ~/.pamiec/memory.db
> UPDATE topic_nodes SET craw='...' WHERE csum LIKE 'Alice%';
> DELETE FROM topic_nodes WHERE id='...';

Run pamiec graph again to see the updated state. Wrong facts in entities have been the most common issue — usually from over-aggressive Haiku extraction. The confidence gate has reduced this dramatically but isn't perfect.

---

File locations

~/.pamiec/
├── memory.db        SQLite — all data
├── checkpoint.json  Per-session capture progress
├── d3.v7.min.js     Cached D3 for offline graph rendering
├── graph.html       Last rendered visualization
└── cron.log         Output from background jobs

To wipe everything and start fresh:

rm -rf ~/.pamiec/memory.db ~/.pamiec/checkpoint.json
pamiec init

---

Troubleshooting

pamiec recall returns nothing. Check whether anything is in the graph yet: pamiec status. If counts are zero, run pamiec capture && pamiec consolidate-session manually to process the active session.

recall_context doesn't appear in Claude Code. Verify: claude mcp list. If pamiec isn't there, re-register with the command in the setup section. Restart Claude Code after registering.

Cron isn't running. Check ~/.pamiec/cron.log for output from the last runs. If it's empty, verify crontab -l shows the entries with the correct binary path.

Bloated entity descriptions. Run pamiec compact. Adjust COMPACT_THRESHOLD_LINES in consolidation.py if 25 lines is wrong for your usage.

Hallucinated entities (concepts treated as entities). The extraction prompt has explicit negative examples but isn't perfect. Edit or delete bad nodes directly via SQLite. If a class of hallucination keeps recurring, add it to the negative examples in the prompt.

---

Architecture in depth

See ARCHITECTURE.md for the data model, schemas, algorithms, and design choices.