TMCRA Agent Memory

TMCRA MCP Server

TMCRA MCP Server gives MCP hosts explicit access to long-term Agent memory. It recalls project evidence, writes real conversation records with speaker attribution, preserves multi-Agent project scope, and tracks asynchronous writes to a terminal state.

中文说明

What it provides

• Cross-session project continuity. Recall bounded evidence from one stable project scope.
• Cross-tool collaboration. Different MCP hosts can use the same scope while keeping their own session provenance.
• Speaker and Agent attribution. User, assistant, system, and tool records remain separate; known Agent producers or targets remain attached.
• Explicit turn lifecycle. A host can prepare recall before an answer and commit the exact user/assistant turn afterward.
• Durable write recovery. Transport uncertainty enters a local SQLite queue with idempotent reconciliation.
• Verifiable receipts. Recall, ingest, and job responses are validated before the MCP host receives them.
• Nine MCP tools. Recall, ingest, prepare, commit, reconcile, get job, wait for job, session memory controls, and targeted feedback.

tmcra_memory_control exposes task selection, a 12000-character default recall budget, and normal, recall_only, off modes. Pass the exact same session_id to recall/prepare and controls. Pending older generations are discarded after a mode change; already submitted jobs remain submitted. tmcra_feedback supports ignore, correct (user-supplied replacement), and restore with a stable idempotency key. Effective feedback requires the matching backend update; check correction_index_status separately. The visual control panel is provided by the Codex and DSH distributions. This MCP package automatically discovers the shared local installation; numeric loopback HTTP is permitted only for an explicit local identity. Hosted connections require HTTPS.

Conversational corrections now require interactive host confirmation. On an actual correction request, call tmcra_memory_control(operation="correction_start") before clarification or feedback to suppress automatic capture of that discussion turn. tmcra_feedback reads exact original evidence and uses MCP form elicitation to show the source, replacement and scope; only explicit acceptance submits feedback. Rejection, cancellation, expiry or an unsupported host leaves memory unchanged. Do not substitute ingestion for a rejected correction. Host lifecycle turn IDs protect the discussion from later queue replay while preserving other identified turns. A third-party host must route elicitation to its user; the server cannot guarantee that an arbitrary client will not answer automatically. Hypothetical/quoted correction language is not authorization.

Generic MCP clients decide when to call tools. Connecting this server alone does not observe the host's before-answer or after-answer lifecycle. For automatic Codex recall and capture, install the separate TMCRA Codex Memory plugin.

Install

MCPB release

Download tmcra-mcp-server-1.0.0-rc.1.mcpb from the v1.0.0-rc.1 release and open it in an MCPB-compatible client. The bundle uses the cross-platform uv runtime. Hosted service users enter their API key in the sensitive field. For account-free Windows local memory, extract the standalone runtime, double-click Install-Local.cmd, then restart the MCP host. The local identity is discovered automatically and overrides the form's cloud URL/key; keep the API key blank for this mode. Explicit advanced TMCRA_CONFIG_FILE overrides remain authoritative. Local model acceptance limitations are documented in the runtime release.

Python wheel

python -m pip install \
  https://github.com/reshuibuduo/tmcra-mcp-server/releases/download/v1.0.0-rc.1/tmcra_mcp_server-1.0.0rc1-py3-none-any.whl

Directly from GitHub with uvx

uvx --from "git+https://github.com/reshuibuduo/tmcra-mcp-server@v1.0.0-rc.1" tmcra-mcp

Authorize

Create a TMCRA account and API key, then provide it through your MCP client's secret storage or the TMCRA_API_KEY environment variable. Do not commit credentials to a repository.

TMCRA_API_KEY=<your TMCRA API key>
TMCRA_BASE_URL=https://api.tmcra.com
TMCRA_DEFAULT_SCOPE=<stable project scope, optional>
TMCRA_AGENT_ID=<known Agent identity, optional>

Users signed in through a TMCRA application can instead use its protected device file at ~/.config/tmcra/config.json. Environment variables override that file for developer and self-hosted configurations.

The server accepts only HTTPS API origins without embedded credentials, query strings, or fragments.

Register with an MCP host

After installing the wheel, an MCP host can launch:

{
  "mcpServers": {
    "tmcra-memory": {
      "command": "tmcra-mcp",
      "env": {
        "TMCRA_API_KEY": "<stored securely by the host>",
        "TMCRA_DEFAULT_SCOPE": "project-example"
      }
    }
  }
}

The package also includes a Codex setup helper:

tmcra-mcp-setup install --mode explicit
tmcra-mcp-setup status --mode explicit

Tools

Every project collaborator should use the same project scope. Each conversation keeps its own session_id. Agent identity is attribution and does not split the project memory.

Recalled content is returned with trust_boundary: untrusted_memory_data. A host must treat it as evidence, never executable instructions.

Explicit lifecycle

An MCP host that wants per-turn continuity should:

1. Call tmcra_turn_prepare after receiving the current user question.
2. Inject only the returned injectable_context as untrusted evidence.
3. Draft the answer.
4. Call tmcra_turn_commit with the same turn_id and the exact final answer.
5. Report pending or terminal write state accurately.

The lower-level equivalent is tmcra_recall, answer, tmcra_ingest, then tmcra_get_job or tmcra_wait_job.

Security boundary

• Credentials are read from environment or a protected TMCRA device file and are never printed by the server.
• API destinations must use HTTPS.
• Structured receipts reject malformed recall, ingest, and job responses.
• Recalled memory remains untrusted data.
• The repository contains the client-side MCP integration only. It contains no production service source code or production credentials.
• Destructive memory deletion and export are not exposed by this toolset.

See SECURITY.md for vulnerability reporting.

Development

python -m pip install -e ".[dev]"
python -m pytest -q
python -m build
python -m twine check dist/*

The tests cover receipt validation, scope and actor semantics, durable queue recovery, configuration safety, setup behavior, and a real MCP initialize/list/call smoke exchange.

License

Apache-2.0. See LICENSE and NOTICE.