Connect each human-machine turn from DeepSeek Harness to a local TMCRA memory service. Retrieve relevant evidence first, then inject it. Store questions and answers by role, with automatic queue retry on write failure.
- Language
- Python
- License
- Apache-2.0
- Branch
- main
Install
$ dsh plugin --profile web add github:reshuibuduo/tmcra-memory#path:integrations/deepseek-harness-localRun the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial
Install via your agent
Install the DeepSeek Harness plugin reshuibuduo/tmcra-memory/integrations/deepseek-harness-local for me: review the repository at https://github.com/reshuibuduo/tmcra-memory first, then run the install command and verify the plugin loads successfully.
Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.
One-sentence Positioning
Connects every human-AI turn accepted by the host in DeepSeek Harness to the TMCRA local-only memory service running on your computer — recalls relevant content from the local evidence base before the model thinks, then stores questions and answers separately by role, with automatic retry queuing on write failure.
Core Capabilities
- Injects recall evidence at the very front of the
agent/pre-stephook ({ prepend: true }) into the message list, passing it as plugin data withtrust="untrusted"marking to avoid being treated as instructions - At the start of each turn, automatically retries outbox writes accumulated from the previous turn, clearing failed tasks from
~/.tmcra/integrations/outbox/*.json - Captures turn end in the
session/eventhook, writing to the database separately by three-level identity (agentPreset / subagent / agent), distinguishing primary from subagent - On write failure, atomically writes payload to local outbox file for automatic retry next turn; does not throw blocking errors to host, lets Harness continue by default
- Project identity resolution: prioritizes reading
.tmcra/project.jsonmarker, otherwise falls back to git remote → git root → cwd path hash, ensuring writes to the same project bucket as Codex, Claude and other local integrations - Enforced loopback:
baseUrlmust be127.0.0.1/localhost/::1and cannot contain path / query / userinfo; any public address gets rejected by schema
Technical Implementation
- Language: TypeScript (
type: module, outputdist/index.mjs) - Key Dependencies:
@deepseek-ai/cordis(host service container),@deepseek-ai/dsh-agent(agent/pre-step/PreStepDecisiontypes),@deepseek-ai/dsh-llm(createUserMessageinjection for recall),@deepseek-ai/schemastery(config schema validation) - Architecture Pattern: Cordis function plugin,
name = "tmcra-local-memory",inject = ["agents"]; usesctx.on("agent/pre-step", ..., { prepend: true })to prepend recall content to the end ofmessagesbefore all downstream pre-step handlers; usesctx.on("session/event")to listen forturn/endevents for writeback;ctx.effect()wraps final cleanup of all in-flight writes. SharesloadConfig/rememberMessage/flushOutbox/resolveProjectfromintegrations/local-agent-hooks/lib/local_memory.mjs, ensuring project identity, token validation, and loopback checks are completely consistent with Codex, Claude and other local TMCRA integrations - Entry File:
integrations/deepseek-harness-local/src/index.ts(single file; side-effect logic also lives inapply(ctx, config))
Applicable Scenarios
Use when you already have a TMCRA local-only memory running (no public network, no TMCRA account or subscription required), but DeepSeek Harness's Agent doesn't have access to this memory by default. This plugin takes over Harness's pre-step and turn/end lifecycle, allowing the model to see relevant evidence you've accumulated in the past via Codex, Claude or other TMCRA integrations before each answer, and archives this Q&A by role. Typical use case is personal long-term project memory — when you switch between multiple AI coding tools, they all inject the same local evidence and write back the same answers, ending up with a continuous, cross-tool project history rather than starting from scratch with every new session.
Prerequisites & Compatibility
| Dependency | Min Version | Description |
|---|---|---|
| TMCRA local runtime | Any version that produces ~/.tmcra/config/runtime/local-runtime.json | Deployed via scripts/install-local.ps1 / .sh; this plugin doesn't bundle the runtime and throws "TMCRA local integration is not configured" without it |
| Shared integration config generator | integrations/local-agent-hooks/scripts/configure.mjs --runtime-config … | Provided by the local-agent-hooks subpackage in this monorepo; must run once before deploying the Harness plugin |
| DeepSeek Harness host | 0.1.0-rc.5+ (peerDependencies locked to <0.2) | peerDependencies lists @deepseek-ai/cordis ^4.0.0 <5, @deepseek-ai/dsh-agent / dsh-llm / dsh-session ^0.1.0-rc.5 <0.2; testing and docs target 0.1.0-rc.6 |
| Node.js | `^22.19.0 | |
| Platform | — | Cross-platform; uses process.platform === "win32" in local-agent-hooks/lib/local_memory.mjs to distinguish Windows ACL from POSIX 0600/0700 permissions |
| Native modules | — | None; only Node built-ins node:crypto / node:fs/promises / node:http |
Installation
dsh plugin --profile web add github:reshuibuduo/tmcra-memory#path:integrations/deepseek-harness-local
Configuration Options
| Config | Type | Description | Default |
|---|---|---|---|
configPath | string | Absolute path to TMCRA local integration config file; if not filled, reads ~/.tmcra/local-integration.json (can also be temporarily overridden via env var TMCRA_LOCAL_INTEGRATION_CONFIG) | ~/.tmcra/local-integration.json |
projectId | string | Forces project identity to a fixed string; if not filled, resolves from current cwd / git / marker | Auto-resolved from cwd or git |
recallFailureMode | "raise" | "continue" | Whether to directly throw error and abort Harness on recall stage error, or only log warn and continue (writes proceed as normal) | continue |
recallTimeoutMs | number (ms) | Maximum allowed duration for a single recall request; actually clamped to 1000–180000ms | 120000 |
ingestTimeoutMs | number (ms) | Maximum allowed duration for a single recall/write request; also clamped to 1000–180000ms | 120000 |
FAQ
Q: Model responses became slower after enabling. What should I do?
A: Recall blocks before the model's first inference. Two common causes: TMCRA local service responding slowly, or recall hitting content too large and getting truncated to 24000 characters. You can first lower topK in ~/.tmcra/local-integration.json (default 8, min 1, max 32), then consider reducing recallTimeoutMs to let Harness take the "timeout-give-up-recall" fast path.
Q: I don't want the model to see historical evidence for a certain project. How to disable it?
A: Placing an empty .tmcra/project.json in that repository root won't work; the correct approach is to create a separate dsh profile for that project, set recallFailureMode to raise in cordis.patch.yml, and point configPath to a config file that intentionally can't be read — this way Harness will directly error and abort during pre-step, preventing any content from being injected.
Q: How to uninstall? How to completely clear local memory?
A: Uninstall via dsh plugin --profile web remove <name>; this plugin has no built-in persistent data. All data writes to external TMCRA service, outbox, and token files — delete ~/.tmcra/ (note: this will also clear evidence from other local TMCRA integrations like Codex and Claude).
Q: Installation directory has spaces or Chinese characters; npm pack reports path errors after Harness starts. What now?
A: This is a known bug in Harness preview. case "$PACKAGE_DIRECTORY" in *[! -~]*|*' '*) in scripts/install-deepseek-harness-local.sh actively detects and errors out; the fix is to change TMCRA_DSH_PACKAGE_DIRECTORY to a short ASCII path without spaces (e.g., D:\tmcra-packages or ~/.tmcra/packages).
Q: Error "TMCRA local hooks refuse non-loopback API URLs" — why?
A: Because validateLoopbackBaseUrl requires baseUrl to be 127.0.0.1 / localhost / ::1, protocol must be http: / https:, and cannot contain path / query / userinfo. This is to prevent token files from accidentally being sent to non-local services. If you want to connect to another machine's TMCRA on LAN, that TMCRA service must also be configured to restrict to loopback to work with this plugin.
Q: Can primary agent's recalled evidence be seen by subagents?
A: This implementation doesn't directly handle cross-subagent recall isolation. Each recall is triggered by its own agent/pre-step turn; when subagent triggers, session.header.origin === "subagent" and parent_session_id are recorded separately, so the write side can distinguish primary/subagent; however, recall's visibility scope currently depends on what the TMCRA server returns by project_id, with no client-side secondary filtering.
Q: No TMCRA runtime but plugin already added to profile. What happens?
A: Each human-AI turn accepted by Harness, the pre-step hook throws TMCRA local integration is not configured: /home/.../.tmcra/local-integration.json during the loadConfig await; since default recallFailureMode === "continue", the error is swallowed by warn(ctx, "prepare", error), writes are skipped, Harness continues. This turn has neither recall injection nor any messages written to the database — need to start TMCRA locally first and open a new session to backfill history.
Difficulty Level
Advanced — must first have an external TMCRA local runtime, have run the shared config generator once, understand the semantics of distinguishing pre-step / turn/end lifecycle hooks, and have basic familiarity with the schema and outbox paths in ~/.tmcra/local-integration.json.
Known Issues & Limitations
- Harness preview cannot correctly handle spaces or non-ASCII characters in tarball paths; install script actively rejects and provides error message (README.md:26 / scripts/install-deepseek-harness-local.sh:13-19)
baseUrlschema hard-limited to loopback + no path + no query + no userinfo; any LAN IP or public address throws error directly (lib/local_memory.mjs:104-117)recallFailureModedefaults to"continue", when TMCRA service is unavailable long-term, only warns in logs, host continues but current turn neither recalls nor writes (src/index.ts:228 / src/index.ts:237-239)flushOutboxretries max 8 items at a time (MAX_OUTBOX_BATCH = 8), and uses "break on any file failure" strategy when iterating outbox files; when TMCRA service remains unavailable, new writes from this turn all stay in outbox waiting for next turn (lib/local_memory.mjs:12 / lib/local_memory.mjs:321-336)recallTimeoutMsandingestTimeoutMsschema forces clamping to 1000–180000ms, out of range throwstimeout must be between 1000 and 180000 ms(src/index.ts:102-108)- Deployed TMCRA integration config schemaVersion must be 1, otherwise throws
unsupported schema(lib/local_memory.mjs:137-139) - While recalled evidence in source code declares "current request takes priority when conflicting with current request," there is no runtime mechanism preventing the model from treating it as instructions — schema serves only as a hint
TMCRA gives long-running agents persistent, source-traceable memory across sessions and applications. A user prompt triggers recall from the owner-global and current-project scopes, followed by a USER source record; after the answer, a separate ASSISTANT source record is stored.
This repository includes an owner-local runtime. Clone it, choose an OpenAI-compatible API endpoint or a local generation model, and run the complete memory service on 127.0.0.1. No TMCRA account or production server is required.
Feature guide
| Capability | What the user gets |
|---|---|
| Automatic memory loop | Recall and USER-source write before the host runs, followed by a separate ASSISTANT-source write |
| Cross-session and cross-application continuity | Tools working on the same project share progress without another project leaking into it |
| Project isolation and owner-global memory | Project content remains partitioned; explicitly selected user context can be reused across projects |
| Source / Fast / Slow layers | Inspectable source records plus derived memory for fast retrieval and deeper relationships |
| Provenance-aware injection | Candidate memories, evidence windows, roles, sources, and retrieval traces for the next agent prompt |
| Visual Atlas | A project/session/episode/evidence graph of personal memory |
| Personal Knowledge | Evidence-cited learned, project, and personal knowledge pages |
| Local models and BYOK | Run structured writing and knowledge curation through a local model or the user's OpenAI-compatible API |
| Usage ledger | Provider, model, task, token, cache, and latency records with no TMCRA service charge |
| Data control | Inspect source messages and delete one message or an entire project with grounded derivatives |
Automatic write and recall
One complete turn is driven by host lifecycle events:
- Resolve a stable project identity from the current repository or working directory, then retry pending writes.
- Query both the owner-global and current-project scopes using the current user prompt.
- Rank and deduplicate candidates into role- and source-attributed
evidence_windows, then produce injectableprompt_evidence. - Persist the USER source before the host loop and the separate ASSISTANT source after completion. Retain the application, native thread, message ID, and actor metadata on both.
- Recall failures let the host continue by default. Failed writes enter an OS-user-private outbox and retry on the next lifecycle event.
The recall response also includes candidate counts and timing per scope. Injected context carries an explicit trust boundary: memory evidence is data and cannot override system or user instructions.
Projects, sessions, and cross-tool continuity
Project identity is resolved from .tmcra/project.json, Git origin, Git root, or the canonical working directory, in that order. Codex, DeepSeek Harness, and other adapters opened in the same repository share the project:<id> memory while preserving their own source_app, native thread, session, role, and agent identities.
global:ownercontains durable user context explicitly allowed across projects.project:<id>contains requirements, decisions, progress, problems, and agent work products.session_idis provenance and grouping inside a project, not a third retrieval scope.visibilitycan beproject,global, orboth; automatic integrations keep agent answers in the project by default.
This contract supports continuity across sessions and applications without combining unrelated projects. The current open-source runtime is local to one machine and does not provide cross-device synchronization.
Structured memory and evidence retrieval
- Source keeps inspectable user and agent messages so every derivative can be traced to a source record.
- Fast / Slow are produced by the structured writer for entities, events, relationships, time, state changes, and cross-turn dependencies.
- Local recall combines the embedding index, released graph-node and path scorers, and Source text matching as an evidence entry point.
- Result packing ranks, deduplicates, and applies Top-K selection before returning
hits,evidence_windows,prompt_evidence, and a per-scopetrace. - Actor provenance remains attached through recall and knowledge curation, keeping user statements, agent proposals, and accepted decisions distinct.
Visual Atlas and Personal Knowledge
Visual Atlas projects project/session hierarchy, episodes, evidence nodes, relationships, time, actor role, source application, and stable source identifiers into data that a desktop client, web client, or custom visualizer can render through the /graph endpoint.
Personal Knowledge turns a complete Visual Atlas snapshot into readable pages across three collections:
learned: concepts, methods, research notes, and reusable lessons;project: requirements, decisions, milestones, current state, incidents, and open questions;personal: explicitly stated profile details, preferences, people, and experience.
Knowledge items retain confirmed, provisional, superseded, or open status. Every claim and section must cite an existing evidence ID. Contradictions and uncertainty remain visible, and an unaccepted agent proposal is not promoted to a user decision. Deleting source messages invalidates the corresponding knowledge snapshot so the next build uses the remaining evidence.
Models, usage, and local operations
Writer and Personal Knowledge policies can be configured independently. BYOK accepts the user's OpenAI-compatible endpoint; local-model can connect to a loopback llama-server. Embedding profiles cover different resource levels. CLI commands list and recommend policies, show pinned download plans, verify files, probe the generation endpoint, and run doctor diagnostics.
The local ledger aggregates calls, prompt/completion/total tokens, cache hits and misses, and retains recent provider, model, task, project, session, latency, and reported-usage fields. Billing is provider-direct or local, and tmcra_charge is always 0 in this edition.
Integration status
| Host | Automation | Current status |
|---|---|---|
| Codex | Recall before answer; separate USER / ASSISTANT writeback; outbox retry | One-command setup; passed real local FastAPI cross-tool E2E |
| DeepSeek Harness | Native agent/pre-step recall; turn/end writeback; multi-agent identity | Technical preview; passed real AgentLoop two-session, type, build, and package checks |
| Claude Code | Shared owner-local hook lifecycle | Manual registration; passed shared-hook and cross-tool E2E |
| ZCode | Shared owner-local hook lifecycle | Manual registration; clean-host packaging acceptance remains open |
| Other tools | The same lifecycle through the loopback REST API | API available; the host still needs a verified lifecycle seam |
This public repository is a source release. It does not yet include a desktop GUI, automatic scanning and selective import of historical chats, cross-device synchronization, or one-command installers for hosts such as Qimi Code and GLM Code. Hosted accounts, subscriptions and billing, staff tools, tenant management, production deployment, and operational control planes are also excluded. The exact boundary is documented in Public release boundary and enforced by scripts/audit_public_release.py.
Runtime flow
flowchart LR
PROMPT["Current user prompt"] --> SCOPES["Owner-global + current-project recall"]
SCOPES --> LAYERS["Source + Fast + Slow retrieval"]
LAYERS --> PACK["Attributed evidence windows"]
PACK --> AGENT["Agent answer"]
PROMPT --> USERWRITE["Write USER record"]
AGENT --> AGENTWRITE["Write AGENT record"]
USERWRITE --> PROJECT["Project memory"]
AGENTWRITE --> PROJECT
USERWRITE --> GLOBAL["Optional owner-global memory"]
A session is provenance within a project, not an independent recall scope. This keeps conversations in one project connected while preventing ten unrelated projects from collapsing into one graph.
Local quick start
Requirements: Python 3.12, Git with Git LFS, and at least 8 GiB system RAM. The default BYOK installation downloads the released graph scorers, one local embedding model, PyTorch, and runtime dependencies.
Windows PowerShell
git clone https://github.com/reshuibuduo/TMCRA-Agent-Memory.git
cd TMCRA-Agent-Memory
git lfs install
powershell -ExecutionPolicy Bypass -File .\scripts\install-local.ps1
powershell -ExecutionPolicy Bypass -File .\scripts\start-local.ps1
The installer asks for a credential-free OpenAI-compatible /v1 URL, a model ID, and the user's API key. The key is written only to .tmcra/config/runtime/secrets/byok-api.key; it is never serialized into the runtime JSON.
Linux or macOS
git clone https://github.com/reshuibuduo/TMCRA-Agent-Memory.git
cd TMCRA-Agent-Memory
git lfs install
bash scripts/install-local.sh
bash scripts/start-local.sh
For non-interactive installation, set TMCRA_BYOK_BASE_URL, TMCRA_BYOK_MODEL, and TMCRA_BYOK_API_KEY for the installer process. See Local deployment for GPU selection, model profiles, local-generation mode, health checks, and uninstall behavior.
After starting the API, run .tmcra/venv/bin/python scripts/smoke_local_api.py
(or .\.tmcra\venv\Scripts\python.exe .\scripts\smoke_local_api.py on
Windows) to verify write, recall, provenance, graph, model-generated and
evidence-cited Personal Knowledge, usage, and deletion through one disposable
project. It fails if knowledge generation falls back without using the
configured model. Add --allow-knowledge-fallback only when you deliberately
disabled that optional task.
Connect Codex
With the local API running:
powershell -ExecutionPolicy Bypass -File .\scripts\install-codex-local.ps1
Restart Codex, open /hooks, review the four local lifecycle commands, and grant trust. A new prompt then recalls relevant local memory automatically; the prompt and completed answer are stored as separate role-attributed records.
The source release also contains a tested DeepSeek Harness technical preview plus shared Claude Code and ZCode hook manifests. See Local tool integrations for the support matrix and exact acceptance evidence.
Local API
The service listens on http://127.0.0.1:2009. Read the local token from .tmcra/config/runtime/secrets/local-api.token and send it as a bearer token.
Core endpoints:
| Method | Path | Purpose |
|---|---|---|
GET | /v1/health | Secret-free health status |
GET | /v1/projects | List local projects |
GET | /v1/sessions | List session provenance for one project |
POST | /v1/recall | Recall evidence for the current user prompt |
POST | /v1/messages | Persist one attributed source message |
GET | /v1/messages | Inspect stored source messages |
DELETE | /v1/messages/{message_id} | Delete one message and grounded derivatives |
DELETE | /v1/projects/{project_id} | Delete a project, its global derivatives, knowledge, and usage metadata |
GET | /v1/projects/{project_id}/graph | Build the Visual Atlas payload |
POST | /v1/projects/{project_id}/knowledge/build | Build Personal Knowledge |
GET | /v1/projects/{project_id}/knowledge | Read the latest Personal Knowledge snapshot |
GET | /v1/usage | Read local provider-token usage |
The complete request/response contract and turn ordering are in Local API.
Generation choices
BYOK is the default: the user supplies an OpenAI-compatible endpoint, model ID, and API key. The selected model performs structured memory writing and reconciliation, plus Personal Knowledge generation when that projection is enabled. Recall itself stays local and uses the embedding index plus the released graph-node and path scorers; it does not make a provider-model call.
local-model is available for users who want generation to remain on the machine. The recommended full-quality profile is a Qwen3.6 35B-A3B GGUF configured for 32K context through llama-server; its download is approximately 12.74 GiB. The suggested hardware target is an RTX 5090D 32 GB or better. TMCRA also exposes model-policy inspection commands so users can make an explicit resource decision before downloading.
Security and privacy
- The API refuses non-loopback binding.
- Provider keys live in permission-restricted local secret files and are omitted from config, health, usage, and error responses.
- Released scorer weights are loaded with
weights_only=Trueand verified against byte counts and SHA-256 values in the public manifest. - BYOK sends memory-processing prompts to the endpoint selected by the user. Local-model mode keeps those generation calls on loopback.
- Explicit deletion rewrites free SQLite pages and truncates WAL files. It cannot erase copies already held by filesystem backups, snapshots, or an external model provider.
Run the release audit before publishing:
python scripts/audit_public_release.py --history
LongMemEval result
TMCRA achieved 411 / 500 = 82.2% on the released LongMemEval S500 scorecard.
| Task | Correct / total | Accuracy |
|---|---|---|
| Knowledge Update | 71 / 78 | 91.0% |
| Multi-session | 90 / 133 | 67.7% |
| Single-session Assistant | 55 / 56 | 98.2% |
| Single-session Preference | 27 / 30 | 90.0% |
| Single-session User | 67 / 70 | 95.7% |
| Temporal Reasoning | 101 / 133 | 75.9% |
| Overall | 411 / 500 | 82.2% |
The machine-readable scorecard is results/latest_benchmark.json. Reproduction instructions are in benchmarks/longmemeval/. The retained 310/500 artifact is a historical baseline and is labelled separately in results/README.md.
Repository layout
runtime/ owner-local memory engine and loopback API
scripts/ install, start, uninstall, and release-audit tools
integrations/ owner-local Codex, DSH, Claude Code, and ZCode adapters
benchmarks/longmemeval/ maintained LongMemEval reproduction pipeline
models/ released inference weights and integrity manifests
results/ current scorecard and labelled historical artifacts
docs/ deployment, API, security boundary, and training notes
code/ earlier public runtime and adapter snapshots
Developers
- Yu Haoxin (@reshuibuduo) — creator, lead developer, and TMCRA algorithm engineering.
- OpenAI Codex — development and reproducibility engineering assistant.
See AUTHORS.md and CITATION.cff.
License
TMCRA is released under the Apache License 2.0. Third-party datasets, models, and components retain their own licenses; see the relevant notices and model cards.
Read the usage guide →
Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.
Listing badge
[](https://deepseek-plugin.org/plugins/reshuibuduo/tmcra-memory/integrations/deepseek-harness-local)Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.