Lynx docs

Long-term memory for AI agents, kept as plain files on your machine. This page covers everything the CLI and the MCP server do.

Quickstart

Install the CLI from this site (Node 22 or newer), then let it wire your agents:

npm i -g https://lynx.example/lynx.tgz
lnx init --dry-run   # see what it would change
lnx init             # do it

Restart your agent. From then on it gets a digest at session start, can remember and recall, and each Claude Code session is saved for the next dream. Check everything with lnx doctor.

How memory is kept

LayerWhat it holdsWho writes it
TranscriptsSession logs, secrets redacted before writingThe Claude Code stop hook, lnx log, the save_transcript tool
NotesShort facts: a command, a decision and why, a gotcha and its fixYour agent, through remember and update_note
WikiA few linked markdown pages plus _index.md; every write is a versionA dream, after you apply it
DigestThe index and newest notes, handed over at session startBuilt from the above

Search is BM25 over notes and pages. Page titles count four times, and a page with no match of its own that is linked from a match comes along below it. Results need words in common with the query.

Memory is grouped in spaces, one per project folder (the folder's name). Pass --space NAME or set LYNX_SPACE to choose another.

Agents

AgentWhat lnx init sets up
Claude CodeHooks in ~/.claude/settings.json (session start, stop; prompt recall with --prompt-recall) and the MCP server at user scope
CodexThe MCP server through codex mcp add. Run lnx agents-md in a project so Codex uses memory without being asked
CursorAn entry in ~/.cursor/mcp.json
Claude desktop appAn entry in claude_desktop_config.json. Ask for Lynx by name, since the app has memory of its own
Anything elseRun lnx mcp as a stdio MCP server

Every config file is backed up next to itself as .lynx-backup before an edit, and a file that does not parse is left untouched.

Claude Code hooks

HookWhat it does
SessionStart → lnx hook session-startAdds the project digest to the session's context
UserPromptSubmit → lnx hook user-promptOptional. Searches memory with the prompt and adds up to three results that share at least two words with it; adds nothing otherwise
Stop → lnx hook stopCopies the session's text turns into transcripts/cc-<session>.jsonl, scrubbed. A session that grows after a dream counts as new material again

Dreaming

A dream reads the notes and transcripts saved since the last one, compares them with the wiki, and writes a proposal: pages to add or rewrite, and pages to remove, each with a reason. It never writes the live wiki.

lnx status     # what is waiting
lnx dream      # estimate, confirm, propose
lnx diff       # read the proposal
lnx apply      # or: lnx reject

With a key

Save an Anthropic key once with lnx key (stored in ~/.lynx/.env, readable by you only), or set ANTHROPIC_API_KEY. The dream uses claude-opus-5-5 unless you pass --model. It prints a token estimate, asks before sending, and refuses to go past --budget (default 400,000 tokens). Narrow a large backlog with --since 2026-11-01 or --max-inputs 20.

Through your agent

Ask your agent to dream. It calls dream_prepare, rewrites the pages with its own model, and hands the result to dream_submit. Input is capped at 120,000 characters because it travels through the agent's context. The result is the same kind of proposal; the agent cannot apply it.

On a schedule

lnx dream --if-due --yes runs only when at least 5 notes or 20 transcript turns are waiting and the last dream was over 12 hours ago, so it is safe in cron. It still only proposes.

Applying

lnx apply writes each page only if it still matches what the dream read; a page you edited in the meantime is skipped. Every write keeps the previous version: lnx history testing.md, lnx restore testing.md --version 2.

CLI reference

All commands accept --space NAME.

CommandWhat it does
lnx remember "text" [--tags a,b]save one short fact
lnx recall "query" [--limit N] [--kind note|wiki] [--since DATE]search notes and wiki (BM25)
lnx notes [--limit N]list notes, newest first
lnx edit <note-id> "new text"correct a note in place
lnx forget <note-id>delete a note
lnx contextprint the session-start digest
lnx statuswhat is stored and what is waiting
lnx log [--id ID] < turns.jsonappend a transcript from JSON (agents without hooks)
lnx dream [--budget TOKENS] [--since DATE] [--max-inputs N] [--yes] [--if-due] [--dry-run]review new material and propose wiki changes
lnx conflictsfacts in memory that may contradict each other
lnx fadingnotes that have not come up in a long time
lnx map [--open]draw this space as an interactive map (one offline HTML file)
lnx trace <page>where a page came from: each change and its sources
lnx outboundevery call that ever left this machine
lnx proposalslist dream proposals
lnx diff [proposal-id]show what a proposal would change
lnx apply [proposal-id]accept a proposal (every write is a version)
lnx reject [proposal-id]discard a proposal
lnx pageslist wiki pages
lnx read <page>print a wiki page
lnx history <page>versions of a page
lnx restore <page> [--version N]bring back an earlier version
lnx retention [--days 30]delete dreamed transcripts older than N days
lnx spaceslist memory spaces
lnx key [--remove]save the dream key in ~/.lynx/.env
lnx doctor [--json]read-only health check
lnx init [--claude-code] [--codex] [--cursor] [--claude-desktop] [--all] [--prompt-recall] [--dry-run]wire Lynx into your agents
lnx agents-md [--dry-run]add the memory block to ./AGENTS.md (Codex)
lnx mcpMCP server over stdio (19 tools)
lnx hook session-start|user-prompt|stopClaude Code hooks

MCP tools

lnx mcp serves 19 tools over stdio, plus the resource lynx://context. Every tool accepts an optional space. Memory text comes back wrapped and labelled as stored data, never as instructions.

ToolWhat it does
rememberSave one short, self-contained fact a future session would need: an exact command, path, decision and its reason, or a gotcha and its fix. Never secrets.
update_noteRewrite a note that turned out wrong or changed. Find its id with recall or list_notes.
forgetDelete a note by id.
recallKeyword search (BM25) over notes and wiki pages. Use before asking the user something an earlier session may have learned. Matches need shared words, so try the likely terms.
contextThe short digest for this project: the wiki index and the newest notes. Call at the start of a task.
list_notesList notes, newest first.
save_transcriptStore this session's turns so a later dream can learn from them. Only when the user wants it.
read_pageRead one wiki page, e.g. _index.md or testing.md.
list_pagesList all wiki pages.
related_pagesPages linked to or from a page.
page_historyEarlier versions of a page with the reason for each change.
memory_statusWhat is stored, what is waiting for a dream, and whether a dream is worth suggesting.
memory_conflictsPairs of stored facts that may contradict each other (a negation, or the same key with a different value), newer one marked. Check before trusting a fact that matters.
fading_notesNotes that have not been recalled or updated in a long time. Suggest to the user which to keep, fix or forget.
trace_pageWhere a wiki page came from: every change, the dream that made it, and the notes and sessions that dream read.
list_proposalsDream proposals and their status.
show_proposalThe diff of a dream proposal, to summarise for the user. You cannot apply or reject it; the user does.
dream_prepareStart a dream with your own model, only when the user asks for one. Returns the wiki and the new material; rewrite the pages that need it, then call dream_submit.
dream_submitHand in the result of dream_prepare. It becomes a proposal the user reviews; nothing changes until they apply it.

Files

~/.lynx/
├─ .env                      dream key, if saved with lnx key
└─ shop-api/                 one space per project
   ├─ notes.jsonl            one note per line
   ├─ transcripts/*.jsonl    session logs
   ├─ wiki/
   │  ├─ _index.md
   │  ├─ testing.md …
   │  └─ .history/           every earlier version, with its reason
   ├─ proposals/*.json       dream output, open / applied / rejected
   └─ state.json             which transcripts a dream consumed

Everything is plain text. Read it, grep it, back it up, or keep it in git. lnx retention --days 30 deletes transcripts a dream already consumed.

Environment

VariableEffect
LYNX_HOMEWhere memory lives (default ~/.lynx)
LYNX_SPACEForce one space regardless of folder
LYNX_API_KEY / ANTHROPIC_API_KEYKey for dreams (checked before ~/.lynx/.env)
LYNX_MODELDefault dream model
NO_COLORPlain output

Safety