companion-memory

dsh-companion-memory-core (v0)

Local, host-independent long-term memory core for DeepSeek Harness. Plain-text notes, a bounded index, auditable evidence. No runtime dependencies, no external services, no native modules.

Design notes live in the project plan and are not shipped in the npm package.

Current status

The v0 implementation covers the data contract, three-source store, bounded index, keyword recall, layered disclosure, five tools, host llm/stream review, and a read-only client entry. lib/ is generated by npm run build and shipped in the package.

Review borrows the host's ctx.llm.stream() through LlmReviewer; it stays disabled by default via maintenanceMode: off. The idle-review chain (§7-3) is covered end to end by a host-shaped stream test, so no model quota is spent in CI. The client entry (exports["./client"]) registers a read-only sidebar action through the host's slot service; note browsing stays on the tool surface. A custom pane is deferred: host remote namespaces are Typert-generated, so a third-party plugin cannot register a new RPC group at runtime.

When consolidation runs, the model route is borrowed from the current session request header. Set reviewProvider / reviewModel in the profile config to pin a specific one; leaving both empty follows whatever the conversation uses. Every written note carries an evidence quote that is verified verbatim against the input actually shown to the model — fabricated quotes are dropped before they reach disk.

The host exposes no learning / contentMode / toolVerified admission metadata, so unverified tool/result output is deliberately never archived. User and assistant messages are the only long-term sources in v0.

The npm package name is dsh-companion-memory-core, distinct from the GitHub repository name.

Layout

src/core/        host-independent: paths, schema, store, indexer, recall,
                 disclosure, context, review, writer, llm-adapter, llm-reviewer
src/host/dsh/    the only layer allowed to touch the harness
src/client/      read-only sidebar entry (exports["./client"])
lib/             build output, the only code shipped in the npm package

Build and install

npm install --no-package-lock --legacy-peer-deps
npm run build                 # emits lib/**/*.js + .d.ts
npm test
npm pack                      # sanity-check the tarball contents
dsh plugin --profile test add .

Local verification should use a dedicated test profile, never the daily one.

Data location

Default ~/.companion/, overridable with config.memoryRoot or the COMPANION_MEMORY_ROOT environment variable. Everything is plain text and stays on the machine:

MEMORY.md          bounded index (200 lines / 25 KB)
meta.json          schema version, writer epoch, review watermark
notes/*.md         one fact per file, with evidence and sourceRefs
cold/*.jsonl       append-only raw conversation lines
journal/           reserved for v1
persona.md         reserved for v1
profile.md         reserved for v1
state.json         reserved for v1
archive/           soft-archived notes
index/             rebuildable keyword index

Uninstalling the plugin never deletes this directory. memory_forget archives a note and removes its index entry; it does not touch the host's own chat history.

Privacy and capability boundaries

• Memory is unencrypted plain text; any local process can read it. Never store credential values, only pointers to where they live.
• The core never reads credentials and never opens network connections.
• Review requests borrow the host's model through LlmAdapter; the package ships no API key and no fallback provider.
• maintenanceMode: off must produce zero model calls.

Before publishing

1. Confirm peer ranges against the actual dsh release in use (verified against desktop 0.2.2-rc.1 / cordis 4.1.0).
2. Run npm run build, verify lib/ and icon.png are in the tarball, then npm publish.
3. Add the dsh-plugin topic after the repository is at least one day old, then submit one catalog YAML entry data/plugins/1326007879-sys__companion-memory.yml. Note the 24-hour npm release-age window.
4. Keep descriptions factual: stable memory, local notes, bounded index. Do not claim consciousness, emotions, or model training.

Out of scope for v0

Persona/state injection, moods, proactive messages, journaling, vectors, graph links, star map, cross-host adapters, encryption, hash-chain audit, standalone service, model training.