Memory
Opt-in long-term memory that stays on your machine, with every remembered fact reviewable.
Lunos can remember facts across sessions, such as “the billing service owns the invoices table”, and recall the relevant ones in later turns. Memory is off by default. Everything it stores stays on your machine.
Turn it on
{ "memory": { "enabled": true, "scope": ["project"], "model": "small" }}| Key | Default | What it does |
|---|---|---|
enabled | false | Turns memory on. LUNOS_DISABLE_MEMORY=1 turns it off regardless |
scope | ["project"] | "project" keeps memory in .opencode/memory/graph/ in the project. "user" keeps it in the Lunos data directory |
model | "small" | The model that extracts facts when something is remembered: "small" (your small_model), "inherit", or "provider/model". It goes through your normal provider and residency policy |
retrieval.max_tokens | 1500 | The most recalled memory added to one turn |
limits.max_facts | 5000 | The most facts kept per scope |
Memory needs uv and Python 3.10–3.13. It runs Cognee in a local sidecar, with embeddings computed on your machine.
What gets remembered
The agent asks before remembering anything, unless you allow it. Recalled facts are added to a turn as reference context, each with where and when it was learned, and marked as not instructions: they may be outdated, and none overrides you or the system prompt. You can also write notes yourself as Markdown files in .opencode/memory/. The agent needs your permission to edit them, and it can’t edit the stored graph at all.
Review what’s stored
lunos memory list # every fact, with where it came fromlunos memory show <id>lunos memory search <query> # what the agent would recalllunos memory forget <id> # removes the fact and the graph data only it producedlunos memory export # everything, as a versioned bundle you can back up or movelunos memory export --format markdown # one Markdown file per fact, for reviewlunos memory import <path> # a bundle, Markdown or AGENTS.md; previews firstlunos memory purge # delete a memory's facts and graphIn the TUI, /memory opens the same list, ctrl+s exports it and ctrl+o imports.
Take it with you
lunos memory export writes all of memory, both scopes, to one bundle: every fact with its provenance, the graph of entities and relationships (each tied to the facts it came from), your notes, and a manifest with a SHA-256 for every file. SCHEMA.md inside the bundle documents the format, so other tools can read it without Lunos. Add --zip, or --encrypt for a passphrase-locked archive that decrypts with a standard openssl command. Embeddings are left out: they are rebuilt from the facts.
lunos memory import brings a bundle back on another machine, or your AGENTS.md, CLAUDE.md and Claude Code memory notes. Imported memory is treated as untrusted: the bundle’s checksums are verified, every fact goes through the same checks as the agent’s own writes (secrets, instruction-shaped text, size), and you see a preview of what is new, duplicate, conflicting or rejected before anything is written. Imported facts keep their original provenance and are labelled “imported” when recalled.
Share it with your team
Memory can live in a Neo4j database your team runs, instead of on each machine. Set memory.backend with the database’s URL, credentials as {env:} or {file:} references, and the jurisdiction it runs in. Lunos checks that jurisdiction against your residency policy and requires TLS to any other host before it connects. Everyone on the same repository shares its project memory. Lunos doesn’t recall your user memory for anyone else, but anyone with the database’s credentials can read it there. lunos memory migrate --to neo4j moves what you have, with a preview first. The self-hosted guide has the details.
Network
- The first time memory starts, it downloads its Python packages (pinned by hash) and a small embedding model.
- After that, memory makes no network calls of its own. Extracting facts is one more request to your model provider, under your residency policy, and it appears in the audit log.
- With
LUNOS_OFFLINE=1, memory uses only what’s already cached.