Nan Forget

NaN Forget

Long-term memory for AI coding tools.

Your AI forgets everything when the session ends. NaN Forget fixes that.

---

Install (3 steps)

npx nan-forget setup

That's it. The wizard installs Ollama, embeddings, Claude hooks, MCP config, and a project AGENTS.md for Codex-style agents. Restart Claude Code or reopen Codex. Your AI now remembers.

No API keys needed. No Docker needed. Runs locally. Free forever.

---

How It Works

flowchart LR

A["You talk to your AI tool"] --> B["It learns things"] B --> C["nan-forget saves to SQLite"] C --> D["Session ends"] D --> E["New session starts"] E --> F["nan-forget loads context"] F --> G["Your AI remembers"]

1. You work normally. Your agent saves decisions, preferences, and facts to a local SQLite memory database as you go.
2. Session ends. Memories persist in ~/.nan-forget/memories.db. Aging memories get automatically compacted into long-term entries.
3. New session starts. nan-forget loads context from past sessions. Auth decisions from 3 months ago on Project A surface when you work on Project B today.

---

Automatic Memory Handling

You never call save or search manually. Here's what happens behind the scenes:

Claude Code (fully automatic)

Four layers of protection ensure nothing is lost:

1. Auto-recall on every message (UserPromptSubmit hook)
2. Claude saves proactively (directive tool descriptions)
3. Hook catches .md writes (PostToolUse intercept)
4. End-of-session sweep (SessionEnd transcript scan)

Codex, Cursor, and other tools

Codex and similar agents work well with nan-forget, but they usually need instruction files or shell/API fallbacks instead of Claude's hook model:

1. Run setup: npx nan-forget setup
2. Use the generated `AGENTS.md` in your repo. It tells Codex-style agents to sync, search, save, and checkpoint automatically.
3. Use REST or CLI fallback during conversation. Agents can call the REST API on localhost:3456 or local commands like nan-forget sync, nan-forget search, nan-forget add, and nan-forget checkpoint.

The REST API and CLI now mirror the important memory workflows closely enough that memories saved by Claude are searchable from Codex and vice versa.

# Start the REST API

nan-forget api

The system prompt tells your agent exactly what endpoints to call

nan-forget prompt

---

Slash Commands

Type these in Claude Code:

---

Works with Any LLM

Claude uses MCP. Codex can use AGENTS.md plus CLI/REST fallback:

# Start the API

nan-forget api

Get the system prompt for your agent

nan-forget prompt

Codex, Cursor, and Claude all share the same memory database.

curl http://localhost:3456/memories/search?q=auth

curl -X POST http://localhost:3456/memories/sync -d '{"project":"my-app"}' curl -X POST http://localhost:3456/memories/checkpoint \ -H 'content-type: application/json' \ -d '{"task_summary":"Fixed auth regression","problem":"Expired tokens were not refreshed","solution":"Added refresh handling in middleware","files":["src/auth.ts"],"concepts":["auth","jwt"],"project":"my-app"}'

---

Quick Start (CLI)

nan-forget add "We use FastAPI, not Django. Railway deploys faster."

nan-forget add --type decision "Auth is Clerk, not custom JWT" nan-forget search "what auth system" nan-forget stats

---

Architecture (Expert Section)

Everything below is for developers who want to understand how nan-forget works under the hood.

---

The Problem

LLMs have no memory between sessions. Every conversation starts from zero. You re-explain your stack, Claude contradicts decisions from last month, and context disappears when the session ends.

Existing solutions (Mem0) target app developers embedding memory into products. We target you — the developer using AI tools daily who wants AI that just remembers.

Design: Brain-Inspired Two-Layer Memory

flowchart TB

subgraph Short["Short-Term Memory"] MD[".md files Current session context Disposable scratch paper"] end subgraph Long["Long-Term Memory"] DB["SQLite + sqlite-vec ~/.nan-forget/memories.db Semantic search + decay"] end subgraph Auto["Automatic Processes"] Hook["Hooks (3) PostToolUse: .md → DB UserPromptSubmit: auto-recall SessionEnd: transcript sweep"] Consolidate["Consolidation Engine Clusters + summarizes aging memories"] GC["Garbage Collection Decay, dedup, expiry"] end MD -->|"hook intercepts"| Hook Hook -->|"nan-forget add"| DB DB --> Consolidate Consolidate --> DB DB --> GC

Short-term memory = Claude's built-in .md files. Disposable. Current session only.

Long-term memory = SQLite database with sqlite-vec vector search. Single file. Permanent. Searchable across all sessions, all projects, all LLM tools.

Three hooks handle memory automatically:

• PostToolUse intercepts .md file writes and saves them to the DB.
• UserPromptSubmit runs nan-forget recall on every user message, auto-searching memory for relevant context.
• SessionEnd scans the conversation transcript for unsaved decisions and saves the top 5.

Three-Stage Retrieval Pipeline

Memory search follows the same path as human recall:

flowchart LR

Q["Query"] --> S1["Stage 1: Recognition Fast vector match Returns summaries only"] S1 --> S2["Stage 2: Recall Full content fetch Cross-project expansion"] S2 --> S3["Stage 3: Association Spreading activation Related memories surface"] S3 --> R["Results ranked by similarity x decay x frequency x confidence"]

Scoring formula:

final_score = vector_similarity * decay_weight * frequency_boost * confidence_boost

decay_weight = (0.5 ^ (days / 30)) ^ (1 - confidence) frequency_boost = log2(access_count + 1) / 10 + 1 confidence_boost = 0.5 + 0.5 * confidence

High-confidence memories (debate-validated, human-approved) decay much slower and rank higher. A core memory at 0.85 confidence decays at ~15% of normal rate — effectively permanent unless superseded. Cross-project search means auth decisions from Project A surface when you work on Project B.

Consolidation Engine

Aging memories don't just get deleted — they get compacted into long-term entries:

flowchart TB

A["10+ aging memories about the same topic"] --> B["Cluster by project + type

• vector similarity > 0.8"] B --> C{"OpenAI key

available?"} C -->|"Yes"| D["LLM summarizes cluster into 1-2 sentences"] C -->|"No"| E["Deterministic merge concatenate + deduplicate"] D --> F["Save consolidated entry with fresh vector embedding"] E --> F F --> G["Archive originals with backlink"]

Triggers automatically after every 10 saves or 24 hours. No user action needed.

13 MCP Tools

Structured Memories

memory_save accepts structured fields for richer vector representation:

All fields are embedded together into a single vector. Searches for "JWT auth bug" find memories tagged with those concepts even if the content text doesn't match literally.

Memory Tiers

Not all memories are equal. Debate-validated and human-approved memories are core — they decay slower, rank higher in search, and survive garbage collection longer.

Core memories are designed for the upcoming nan-debate system — multi-AI debate results validated by human approval get persisted as high-trust knowledge that almost never fades.

Checkpoint Workflow

After completing a task, call memory_checkpoint with task_summary, problem, solution, files, concepts, and project. Saves the full problem→solution context to long-term memory. Every completed task = one checkpoint.

Memory Compression

memory_compress scans .claude/projects/*/memory/ for .md files already persisted to the DB. Persisted files are replaced with minimal stubs. Reduces context window bloat.

REST API (for non-MCP LLMs)

Shares the same SQLite database as the MCP server — memories saved by Claude are searchab