codewhale/docs/MEMORY.md

User Memory

The user-memory feature gives the model a small persistent note file that's injected into the system prompt on every turn. It's the place to put preferences and conventions that should survive across sessions — "I prefer pytest over unittest", "this codebase uses 4-space indentation", "always run cargo fmt before committing" — without having to repeat them in every conversation.

Memory is opt-in. When disabled (the default), nothing is loaded, nothing is intercepted, and the remember tool isn't surfaced to the model. This keeps zero-overhead behavior for users who haven't asked for the feature.

Enabling memory

Either set the env var:

export DEEPSEEK_MEMORY=on

…or add to ~/.deepseek/config.toml:

[memory]
enabled = true

Restart the TUI after toggling. Disabling is the same in reverse.

The memory file lives at ~/.deepseek/memory.md by default; override with memory_path in config.toml or DEEPSEEK_MEMORY_PATH in the environment.

What gets injected

When memory is enabled and the file exists, every turn's system prompt carries an extra block:

<user_memory source="/Users/you/.deepseek/memory.md">
- (2026-05-03 22:14 UTC) prefer pytest over unittest
- (2026-05-03 22:31 UTC) this codebase uses 4-space indentation
…
</user_memory>

The block sits above the volatile-content boundary in the prompt assembly so it stays inside DeepSeek's prefix cache turn-over-turn. The file is read at every prompt-build call — edits via /memory or external editors land on the next turn, no restart needed.

Files larger than 100 KiB are loaded but truncated, with a marker appended so you can see the cut.

Three ways to add to memory

1. The # composer prefix (#492)

Type a single line that starts with # (but not ## or #!) in the composer:

# remember to use 4-space indentation in this repo

The TUI intercepts the input and appends a timestamped bullet to your memory file. No turn fires — your input is consumed, the status line confirms the path it wrote to, and you can keep typing your real question.

Multi-# prefixes deliberately fall through to normal turn submission so you can paste Markdown headings without surprise.

2. The /memory slash command (#491)

Inspect, clear, or get hints about editing the file:

Subcommand	Effect
/memory	Show the resolved path and current contents inline
/memory show	Alias for the no-arg form
/memory path	Print just the resolved path
/memory clear	Replace the file with an empty marker
/memory edit	Print the ${VISUAL:-${EDITOR:-vi}} <path> shell line

The /memory edit form intentionally just prints the command rather than spawning the editor in-process — that keeps the slash-command handler simple and consistent regardless of which editor you use.

3. The remember tool (auto-update, #489)

When memory is enabled the model gets a remember tool with this shape:

{
  "name": "remember",
  "description": "Append a durable note to the user memory file...",
  "input_schema": {
    "type": "object",
    "properties": {
      "note": { "type": "string", ... }
    },
    "required": ["note"]
  }
}

The model uses this when it notices a durable preference, convention, or fact worth keeping across sessions. The tool is auto-approved because writes are scoped to the user's own memory file — gating them behind the standard write-approval flow would defeat the point of automatic memory capture.

If the model uses remember for transient task state ("I'm currently editing foo.rs") the result is harmless but wastes context. The tool's description explicitly tells the model not to do that — durable, single-sentence notes only.

File format

Memory is plain Markdown with timestamped bullets:

- (2026-05-03 22:14 UTC) prefer pytest over unittest
- (2026-05-03 22:31 UTC) this codebase uses 4-space indentation
- (2026-05-04 09:02 UTC) all PRs need 2 reviewers before merge

You can hand-edit the file in any editor — the loader doesn't care about the timestamp format; it just reads the whole file as the memory block. The timestamp is convention so you can tell when each note was added when grooming the file.

What stays out of memory

Memory is for durable signal. Things that should NOT live there:

• Secrets — no API keys, tokens, passwords. The file is plain text on disk and gets injected verbatim into the system prompt.
• Transient task state — "I'm currently working on the parser" changes every session; it doesn't belong in cross-session memory.
• Conversation snippets — quote-style notes belong in the notes tool (note), not memory.
• Long instructions — anything over a few sentences should live in AGENTS.md (project-level) or in a skill (reusable instruction packs).

Privacy and scope

The memory file lives entirely on your machine in ~/.deepseek/. It's never uploaded to any cloud service — the TUI only ever includes it inline in the system prompt that the LLM provider receives, and only when memory is enabled. If you switch providers (DeepSeek / NVIDIA NIM / Fireworks / etc.) the same memory file is used; the file is provider-agnostic.

The file is per-user, not per-project. If you want project-specific memory, use the project-level AGENTS.md or .deepseek/instructions.md files instead — those are loaded by project_context and live in the repo (or wherever you commit them).

Configuration reference

# ~/.deepseek/config.toml
[memory]
enabled = true                    # default false; or set DEEPSEEK_MEMORY=on
# Path is configured at the top-level (next to skills_dir, notes_path):
memory_path = "~/.deepseek/memory.md"

Setting	Default	Override
Memory enabled	false	[memory] enabled = true or DEEPSEEK_MEMORY=on
Memory file path	~/.deepseek/memory.md	memory_path = "..." or DEEPSEEK_MEMORY_PATH=
Max file size	100 KiB	(none today; truncation marker shows the cut)

Related

• docs/SUBAGENTS.md — sub-agents inherit memory and can use the remember tool too.
• docs/CONFIGURATION.md — full config reference.
• Issue #489 — phase-1 EPIC tracking the work.