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<br/>Current session context<br/>Disposable scratch paper"]
    end
    subgraph Long["Long-Term Memory"]
        DB["SQLite + sqlite-vec<br/>~/.nan-forget/memories.db<br/>Semantic search + decay"]
    end
    subgraph Auto["Automatic Processes"]
        Hook["Hooks (3)<br/>PostToolUse: .md → DB<br/>UserPromptSubmit: auto-recall<br/>SessionEnd: transcript sweep"]
        Consolidate["Consolidation Engine<br/>Clusters + summarizes aging memories"]
        GC["Garbage Collection<br/>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<br/>Fast vector match<br/>Returns summaries only"]
    S1 --> S2["Stage 2: Recall<br/>Full content fetch<br/>Cross-project expansion"]
    S2 --> S3["Stage 3: Association<br/>Spreading activation<br/>Related memories surface"]
    S3 --> R["Results ranked by<br/>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<br/>about the same topic"] --> B["Cluster by project + type<br/>+ vector similarity > 0.8"]
    B --> C{"OpenAI key<br/>available?"}
    C -->|"Yes"| D["LLM summarizes cluster<br/>into 1-2 sentences"]
    C -->|"No"| E["Deterministic merge<br/>concatenate + deduplicate"]
    D --> F["Save consolidated entry<br/>with fresh vector embedding"]
    E --> F
    F --> G["Archive originals<br/>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: