SYMlp / dsh-markdown-memory

dsh-markdown-memory

Markdown folder long-term memory for DeepSeek Harness.

A memory directory holds one markdown file per durable fact, each with YAML frontmatter (name, description, optional metadata) followed by the fact body. An index file (default MEMORY.md) carries one line per memory. This plugin mounts the index and a file listing into every request as a system prompt section; the model reads individual memory files on demand with its file tools.

The format is plain files: human-editable, git-versionable, host-agnostic. Any existing markdown note folder — an Obsidian vault, a Claude Code auto-memory directory, a hand-kept notes folder — works as-is or with a thin index file added.

Install

dsh plugin --profile <name> add dsh-markdown-memory

Then point path at your memory directory in the profile's cordis.patch.yml:

- id: markdown-memory
  name: dsh-markdown-memory
  config:
    path: /absolute/path/to/your/memory
    # indexFile: MEMORY.md
    # maxBytes: 32768
    # sectionOrder: 120

Configuration

Field	Default	Meaning
path	(required)	Absolute path of the memory directory. Load fails when it is missing or not a directory.
indexFile	MEMORY.md	Index file name inside the directory. Injected in full.
maxBytes	32768	Byte bound for the injected section. Longer content is truncated with a notice.
sectionOrder	120	Prompt section order, inside the 100–199 tool-guidance band.

Misconfiguration fails at load with a message naming the field.

Refresh semantics

The directory is read once at plugin load, then re-read at each agent/session-start. Edits made while a session is running become visible at the next session start. A failed refresh keeps serving the last good snapshot and logs a warning.

Model Experience

Memory index section

What the model sees

One system prompt section named markdown-memory:index at order 120:

# Long-term memory

A persistent memory directory is mounted at: /home/user/memory
Each memory is one markdown file with YAML frontmatter (`name`, `description`) followed by the fact.
The index below lists one line per memory. When an index line is relevant to the current task,
read that memory file with your file tools before relying on it. `[[name]]` references link to
the memory file whose frontmatter `name` matches.

## Index (MEMORY.md)

- [Project layout](project-layout.md) — where each subsystem lives
- [Deploy ritual](deploy-ritual.md) — the release steps that must not be reordered

## Memory files (2)

project-layout.md, deploy-ritual.md

Token effect

The section costs the index file size plus a fixed header and the file listing, on every request, bounded by maxBytes (default 32 KiB ≈ 8k tokens; a typical index is far smaller). Memory file bodies cost nothing until the model chooses to read one.

KV Cache effect

The section lives in the system prompt and its text is stable across requests within a session, so it extends the reusable request prefix rather than breaking it. When a session-start refresh picks up changed content, the prefix diverges once at the next request and is stable again afterwards.

Known Limitations and Deferred Work

• Host filesystem only — reads use node:fs directly, not the ctx.fs provider seam; remote or sandboxed filesystem products are not covered.
• No live watching — changes are picked up at session start, not mid-session; there is no fs.watch integration.
• No selective recall — the whole index enters every request; intent- and path-scoped recall of individual memories is the next milestone.
• No write path — the model cannot create or update memories yet; a guarded write tool is planned after recall.
• No Loader smoke test yet — coverage is unit-level against real Context + SystemPrompt composition; a full Loader boot test is planned.

License

MIT