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
| Layer | What it holds | Who writes it |
|---|---|---|
| Transcripts | Session logs, secrets redacted before writing | The Claude Code stop hook, lnx log, the save_transcript tool |
| Notes | Short facts: a command, a decision and why, a gotcha and its fix | Your agent, through remember and update_note |
| Wiki | A few linked markdown pages plus _index.md; every write is a version | A dream, after you apply it |
| Digest | The index and newest notes, handed over at session start | Built 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
| Agent | What lnx init sets up |
|---|---|
| Claude Code | Hooks in ~/.claude/settings.json (session start, stop; prompt recall with --prompt-recall) and the MCP server at user scope |
| Codex | The MCP server through codex mcp add. Run lnx agents-md in a project so Codex uses memory without being asked |
| Cursor | An entry in ~/.cursor/mcp.json |
| Claude desktop app | An entry in claude_desktop_config.json. Ask for Lynx by name, since the app has memory of its own |
| Anything else | Run 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
| Hook | What it does |
|---|---|
SessionStart → lnx hook session-start | Adds the project digest to the session's context |
UserPromptSubmit → lnx hook user-prompt | Optional. 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 stop | Copies 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.
| Command | What 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 context | print the session-start digest |
lnx status | what is stored and what is waiting |
lnx log [--id ID] < turns.json | append 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 conflicts | facts in memory that may contradict each other |
lnx fading | notes 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 outbound | every call that ever left this machine |
lnx proposals | list 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 pages | list 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 spaces | list 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 mcp | MCP server over stdio (19 tools) |
lnx hook session-start|user-prompt|stop | Claude 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.
| Tool | What it does |
|---|---|
remember | Save 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_note | Rewrite a note that turned out wrong or changed. Find its id with recall or list_notes. |
forget | Delete a note by id. |
recall | Keyword 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. |
context | The short digest for this project: the wiki index and the newest notes. Call at the start of a task. |
list_notes | List notes, newest first. |
save_transcript | Store this session's turns so a later dream can learn from them. Only when the user wants it. |
read_page | Read one wiki page, e.g. _index.md or testing.md. |
list_pages | List all wiki pages. |
related_pages | Pages linked to or from a page. |
page_history | Earlier versions of a page with the reason for each change. |
memory_status | What is stored, what is waiting for a dream, and whether a dream is worth suggesting. |
memory_conflicts | Pairs 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_notes | Notes that have not been recalled or updated in a long time. Suggest to the user which to keep, fix or forget. |
trace_page | Where a wiki page came from: every change, the dream that made it, and the notes and sessions that dream read. |
list_proposals | Dream proposals and their status. |
show_proposal | The diff of a dream proposal, to summarise for the user. You cannot apply or reject it; the user does. |
dream_prepare | Start 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_submit | Hand 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
| Variable | Effect |
|---|---|
LYNX_HOME | Where memory lives (default ~/.lynx) |
LYNX_SPACE | Force one space regardless of folder |
LYNX_API_KEY / ANTHROPIC_API_KEY | Key for dreams (checked before ~/.lynx/.env) |
LYNX_MODEL | Default dream model |
NO_COLOR | Plain output |
Safety
- Secrets in known shapes are replaced with [REDACTED] on every write: Anthropic, OpenAI, GitHub, GitLab, Slack, AWS, Google, Stripe and npm keys, JWTs, PEM private keys, raw 32-byte hex keys, credentials inside URLs, bearer tokens, and values of variables named like SECRET, TOKEN, PASSWORD or API_KEY. Keep secrets out of chats anyway.
- Page paths are cleaned to lower-case segments inside the wiki folder; nothing can be written outside it.
- Transcripts and notes are fenced as data in the dream prompt and in every tool reply.
- Files are written atomically and readable by your user only.
