deckspace.dev / DeckSpace / docs / memory

Memory

A markdown knowledge graph that lives in your repo, shared by the app and the CLIs.

Agents forget everything between runs. Memory is the fix: a folder of plain markdown notes an agent can read at the start of a task and write to at the end, so what it worked out last week is still there this week.

It is deliberately not a database. Every note is a .md file you can open, edit, grep, diff and commit like any other file in the project.

Where it lives

Scope	Location	What belongs there
Workspace	`<workspace>/.opxmemory/`	Facts about this project — its architecture, its traps, decisions and why they were made.
Global	DeckSpace’s own app-data directory	Things true across every project — your preferences, how you like work done.

Because the workspace folder sits inside your repo, it is version-controlled with everything else — memory arrives with a git clone and reviews in a pull request. If you would rather it did not, add .opxmemory/ to .gitignore; nothing in DeckSpace depends on it being tracked.

What a note looks like

Optional YAML frontmatter, then markdown. [[Wikilinks]] connect notes and #inline-tags group them. Titles become filenames by slug, so Release runbook becomes release-runbook.md.

---
tags: [deploy, traps]
type: reference
pinned: true
---

The updater manifest is merged, never replaced. Publishing one
platform must not strand another — see [[Release runbook]].

Frontmatter is read by a small hand-parser rather than a full YAML library. It understands key: value, key: [a, b], and a block list under tags: or aliases:. Anything more elaborate is ignored rather than rejected, so an unusual key will not break the note — it just will not do anything.

The same folder, from your agent CLIs

Memory would be of limited use if only the app could read it. DeckSpace writes an .mcp.json into the workspace exposing the same folder over MCP, so an agent CLI reads and writes the notes the app is showing you. One set of files, one brain.

This reaches Claude Code, and not the others

.mcp.json is Claude Code’s configuration convention. Codex, Grok, Aider and the rest do not read that file, so they do not pick memory up automatically — you would point them at the MCP server through their own config. The Plugins page has the full picture.

Finding things — and what leaves your machine

There are two lookups and they behave differently. This is the part worth reading closely.

Feature	How it works	Leaves your machine?
Search Text match across titles, bodies and tags.	Locally, on the files.	never
Recall Meaning-based, for “what do I know about X”.	Embeddings, when a provider is configured.	only if you configure one
Capture session Distils a finished pane run into notes.	Asks a model to summarise the transcript.	yes, each time you run it

By default, nothing is sent anywhere

Embedding is off unless you have set an embedding provider and its key or URL. With none set, recall falls back to local ranking — it still works, it is just keyword-based rather than meaning-based.

If you do set one, note text is sent to it. OpenAI and Gemini are remote services. Ollama is a server you run yourself, so with Ollama configured you get semantic recall and the notes still never leave your machine. Vectors are cached inside .opxmemory/, so the same note is not re-sent on every query.

Capture session is the exception and always calls out. It exists to turn a long pane transcript into a few durable notes, and it does that by asking a model to distil it — so the transcript goes to whichever AI provider you have configured. It runs only when you ask for it, never on its own.

Reading and editing it yourself

Everything the app does to memory, you can do with a text editor. The app adds convenience on top: backlinks for a note, unlinked mentions of its title elsewhere that you can turn into links with one click, tag counts, related notes, and a daily note.

To read it — open .opxmemory/ in any editor. Obsidian understands this layout directly, wikilinks included.
To correct something — edit the file. There is no cache to invalidate; the next read picks it up.
To delete a note — delete the file. Links pointing at it become unresolved, which is visible rather than silent.
To start over — delete the folder. It is recreated empty next time it is used.

A wrong note is worse than no note

Memory is read back as fact by every agent that follows. A stale note saying a file lives somewhere it no longer does will send agents to the wrong place confidently, and keep doing so until someone fixes the file. Prune it like code, and prefer deleting a note you are unsure of over leaving it in.