T2A Memory

T2A Memory gives a host agent durable local memory without turning the memory tool into an LLM client.

The memory tool does not ask for an OpenAI, Anthropic, or Gemini API key. It does not require model, base_url, or provider configuration, run a tool-side local model, or call an LLM API. When memory consolidation requires reasoning, it emits a T2A handoff for the host agent to complete. T2A Memory validates the structured result before committing local memory.

The agent reasons. The tool validates. The workflow resumes.

Requires Node.js 22 or newer.

Install

Install the public core and memory packages into a user-level tool home:

export T2A_TOOL_HOME="${T2A_TOOL_HOME:-$HOME/.t2a/tools}"
mkdir -p "$T2A_TOOL_HOME"
npm install --prefix "$T2A_TOOL_HOME" \
  @t2a-protocol/t2a \
  @t2a-protocol/t2a-memory

T2A="$T2A_TOOL_HOME/node_modules/.bin/t2a"
T2A_MEMORY="$T2A_TOOL_HOME/node_modules/.bin/t2a-memory"

Install the reusable T2A and T2A Memory agent skills:

"$T2A_MEMORY" install --agent auto

This may write skill files under user-level agent directories such as .agents/skills/ and .claude/skills/. A new agent session may be needed before newly installed skills are discovered.

On Windows PowerShell, use the .cmd binaries under node_modules\.bin and PowerShell variable syntax. The T2A README includes a complete cross-platform prompt for a shell-capable local agent.

Try it

First, make the tool-side model boundary visible:

"$T2A_MEMORY" doctor

Then ask T2A Memory to remember a fact:

"$T2A_MEMORY" remember "I prefer concise but structured technical advice."

remember records a raw event and prints a t2a.handoff JSON result. Copy the returned local.task_dir.

The host agent should:

1. Read task.json first.
2. Inspect prompt.md, input.json, permissions, and output.schema.json.
3. Write only the declared output.json, matching the schema.
4. Run core T2A validation.
5. Run T2A Memory domain validation.
6. Commit only after both validation layers pass.

Using the exact task directory returned by remember:

TASK_DIR="<local.task_dir from the handoff>"

"$T2A" validate "$TASK_DIR"
"$T2A_MEMORY" validate "$TASK_DIR"
"$T2A_MEMORY" commit "$TASK_DIR"
"$T2A_MEMORY" read

The host agent may use its own model capability to perform the reasoning. The memory tool does not own that model call.

Commands

• doctor [--json] [--verbose] reports the tool-side model boundary.
• install --agent <auto|claude|codex|generic|custom> [--skill-dir <path>] initializes user-level memory and installs agent skills.
• init initializes user-level memory files.
• remember "<fact>" records a raw event and emits a T2A handoff.
• validate <task-dir> runs memory-domain validation.
• commit <task-dir> applies a validated update to local memory files.
• read [--topic <topic>] [--json] reads canonical memory deterministically.
• status prints user-level memory status.

Home overrides are available for isolated installs and testing:

--tool-home <path>
--memory-home <path>
--agent-home <path>

Resolution order is CLI option, environment variable, then default:

T2A_TOOL_HOME   -> ~/.t2a/tools
T2A_MEMORY_HOME -> ~/.t2a-memory
T2A_AGENT_HOME  -> user home directory

Local files

T2A Memory stores user-level state under the resolved memory home:

<memory-home>/
  memory.json
  MEMORY.md
  journal/events.jsonl
  tasks/memory-<id>/
    task.json
    prompt.md
    input.json
    output.schema.json
  validations/<task-id>.json

The host agent writes task-local output.json. Core T2A validation writes task-local validation.json. T2A Memory writes its domain validation result under validations/ and commits validated records to the canonical memory files.

Do not edit memory.json or MEMORY.md directly. After commit, use t2a-memory status and t2a-memory read for normal verification.

Boundary

• The host agent reasons and writes structured output.json.
• T2A core validates the protocol envelope and output schema.
• T2A Memory validates domain semantics and commits local memory files.

T2A Memory does not implement project-local memory, a scheduler, daemon, queue, watcher, background worker, MCP server, vector database, web UI, remote server, multi-agent locking, leases, retries, or cancellation.

Development

From a T2A source checkout:

cd integrations/t2a-memory
npm install
npm run build
npm test
npm run check:no-llm-sdks
npm run dogfood:pack-smoke

The package smoke test builds and packs both packages, installs them into an isolated temporary home, completes a deterministic fixture handoff, validates and commits memory, checks tamper detection, and removes its temporary files after success.