total-agent-memory MCP工具

What requires manual action

- Re-embed (only if switching embedding model, otherwise skip):

  python -m scripts.reembed --backend openai-3-large --confirm
  

Applies migrations 011-013 idempotently, restarts LaunchAgents, updates dependencies

```

Then restart Claude Code: /mcp restart memory.

What requires manual setup

1. Cloud providers (only if you want to replace/augment Ollama):

export MEMORY_LLM_PROVIDER=openai       # or "anthropic"
export MEMORY_LLM_API_KEY=sk-...
export MEMORY_LLM_MODEL=gpt-4o-mini     # or "claude-haiku-4-5"

2. Install additional hooks (for UserPromptSubmit capture + citation):

./install.sh --ide claude-code   # re-run installer; it now registers user-prompt-submit.sh hook

3. activeContext.md Obsidian integration (if you want markdown projection): ```bash export MEMORY_ACTIVECONTEXT_VAULT=~/Documents/project/Projects # default

Install

Detailed paths (manual / Docker / per-IDE)

Two manual paths. Same 74 tools, same dashboard, different deployment shapes.

Uninstall

All installers preserve ~/.tam/memory.db (legacy installs: ~/.claude-memory/memory.db) and your config files; only services + hook registrations are removed.

./install.sh --uninstall          # macOS/Linux/WSL2 — removes LaunchAgents OR systemd units
.\install.ps1 -Uninstall          # Windows — unregisters Scheduled Tasks + cleans settings.json

Path B — Docker (everything containerized, cross-platform)

git clone https://github.com/vbcherepanov/total-agent-memory.git
cd total-agent-memory
bash install-docker.sh --with-compose

Brings up 5 services:

First run pulls qwen2.5-coder:7b (~4.7 GB) + nomic-embed-text (~275 MB) — 5–10 min cold start.

GPU note: Docker Desktop on macOS doesn't forward Metal. Native install is faster on Mac. On Linux with NVIDIA Container Toolkit, uncomment the deploy.resources.reservations.devices block in docker-compose.yml.

pulls v9 src, installs new entry-points (tam, tam-lookup, lookup-memory; legacy: ctm-lookup),

Ollama setup (optional but recommended)

Without Ollama: works fully — raw content is saved, retrieval via BM25 + FastEmbed dense embeddings.

With Ollama: you also get LLM-generated summaries, keywords, question-forms, compressed representations, and deep enrichment (entities, intent, topics).

brew install ollama     # or: curl -fsSL https://ollama.com/install.sh | sh
ollama serve &
ollama pull qwen2.5-coder:7b        # default — best quality/speed on M-series
ollama pull nomic-embed-text        # optional, alternative embedder

Quickstart — pick one

All seven channels land at the same MCP server. The npx and ./install.sh paths additionally configure IDE-specific MCP entries and hooks. Other channels start the server bare — you wire the IDE afterwards (see docs/installation.md).

The reranker is an extra, not a dependency. A base install is 97 packages and ~113 MB of wheels: fastembed runs the embeddings through ONNX and no torch is resolved anywhere. The CrossEncoder / BGE reranker needs the torch stack, which on Linux drags in the whole nvidia-cu* set — 147 packages and ~3.1 GB — so it ships separately, and the default MEMORY_MODE=fast does not use it. Turn it on with MEMORY_MODE=deep (or MEMORY_RERANK_ENABLED=true) and install it:

pip install "total-agent-memory[rerank]"      # pip / uvx / pipx
pip install -r requirements-rerank.txt        # clone / Docker

Upgrade from v11.x? Whatever channel you pick will auto-migrate ~/.claude-memory/ → ~/.tam/ on first run and keep a symlink for backward compat. No manual data move required.

---

Quick start

v11 default is MEMORY_MODE=fast. No LLM, no Ollama, no network in the save/search/recall hot path. To restore v10.5 synchronous-LLM behaviour set export MEMORY_MODE=deep. Mode switching: LAUNCH.md § Tuning.

Once installed, in any Claude Code / Codex CLI / Cursor session:

1. Resume where you left off (auto on session start, but you can also invoke)

session_init(project="my-api")
→ {summary: "yesterday: migrated auth middleware to JWT",
   next_steps: ["update OpenAPI spec", "notify frontend team"],
   pitfalls: ["don't revert migration 0042 — dev DB already migrated"]}

2. Save a decision (agent does this automatically after hooks are registered)

memory_save(
  type="decision",
  content="Chose pgvector over ChromaDB for multi-tenant RLS",
  context="WHY: single Postgres instance, per-tenant row-level security",
  project="my-api",
  tags=["database", "multi-tenant"],
)

3. Recall across sessions / projects

memory_recall(query="vector database choice", project="my-api", limit=5)
→ RRF-fused results from 6 retrieval tiers

4. Predict approach before starting a task

workflow_predict(task_description="migrate auth middleware to JWT-only")
→ {confidence: 0.82, predicted_steps: [...], similar_past: [...]}

5. Check a file's risk before editing (auto via hook, also manual)

file_context(path="/Users/me/my-api/src/auth/middleware.go")
→ {risk_score: 0.71, warnings: ["last 3 edits caused test failures in ..."], hot_spots: [...]}

6. Get full stats

memory_stats()
→ {sessions: 515, knowledge: {active: 1859, ...}, storage_mb: 119.5, ...}

---

60-second demo

You:     "remember we picked pgvector over ChromaDB because of multi-tenant RLS"
Claude:  ✓ memory_save(type=decision, content="Chose pgvector over ChromaDB",
                       context="WHY: single Postgres, per-tenant RLS")

[3 days later, different session, possibly different project directory:]

You:     "why did we pick pgvector again?"
Claude:  ✓ memory_recall(query="vector database choice")
         → "Chose pgvector over ChromaDB for multi-tenant RLS. Single DB
            instance, row-level security per tenant."

It's not just retrieval. It's procedural too:

You:     "migrate auth middleware to JWT-only session tokens"
Claude:  ✓ workflow_predict(task_description="migrate auth middleware...")
         → confidence 0.82, predicted steps:
             1. read src/auth/middleware.go + tests
             2. update session fixtures in tests/
             3. run migration 0042
             4. regenerate OpenAPI spec
           similar past: wf#118 (success), wf#93 (success)

---

Cloud providers (optional)

Use OpenAI, Anthropic, or any OpenAI-compat endpoint (OpenRouter, Together, Groq, DeepSeek, LM Studio, llama.cpp) instead of local Ollama.

OpenAI:

export MEMORY_LLM_PROVIDER=openai
export MEMORY_LLM_API_KEY=sk-...
export MEMORY_LLM_MODEL=gpt-4o-mini

Anthropic:

export MEMORY_LLM_PROVIDER=anthropic
export MEMORY_LLM_API_KEY=sk-ant-...
export MEMORY_LLM_MODEL=claude-haiku-4-5

OpenRouter (100+ models via one endpoint):

export MEMORY_LLM_PROVIDER=openai
export MEMORY_LLM_API_BASE=https://openrouter.ai/api/v1
export MEMORY_LLM_API_KEY=sk-or-...
export MEMORY_LLM_MODEL=anthropic/claude-haiku-4.5

Per-phase routing (cheap model for bulk, quality for compression):

export MEMORY_TRIPLE_PROVIDER=openai
export MEMORY_TRIPLE_MODEL=gpt-4o-mini
export MEMORY_ENRICH_PROVIDER=anthropic
export MEMORY_ENRICH_MODEL=claude-haiku-4-5

Embeddings (dimension must match existing DB or re-embed required): ```bash export MEMORY_EMBED_PROVIDER=openai export MEMORY_EMBED_MODEL=text-embedding-3-small # 1536d

Configuration

Environment variables (all optional):

MCP tools reference (74 tools)

TypeScript SDK

For Node.js / browser / any TS project that isn't an MCP-native agent:

npm i @vbch/total-agent-memory-client

import { connectStdio } from "@vbch/total-agent-memory-client";

const memory = await connectStdio();

await memory.save({
  type: "decision",
  content: "Picked pgvector over ChromaDB for multi-tenant RLS",
  project: "my-api",
});

const hits = await memory.recallFlat({
  query: "vector database choice",
  project: "my-api",
  limit: 5,
});

Also ships LangChain adapter example, procedural-memory integration, and HTTP transport (for team / serverless setups).

Package repo: github.com/vbcherepanov/total-agent-memory-client

---

Token-efficient 3-layer workflow

When you only know the topic but not which records matter, use progressive disclosure:

1. Index — memory_recall(query="auth refactor", mode="index", limit=20) → ~2 KB of {id, title, score, type, project, created_at} per hit. No content, no cognitive expansion.
2. Timeline — memory_recall(query="auth refactor", mode="timeline", limit=5, neighbors=2) → top-K hits padded with ±neighbours from the same session, sorted chronologically.
3. Fetch — memory_get(ids=[3622, 3606]) → full content for ONLY the IDs you chose (max 50 per call, detail="summary" truncates to 150 chars).

Typical saving: 80-90 %% fewer tokens vs memory_recall(detail="full", limit=20) when you end up using 2-3 of the 20 hits.

<details> <summary><b>Core memory (15)</b></summary>

memory_recall · memory_get · memory_save · memory_update · memory_delete · memory_search_by_tag · memory_history · memory_timeline · memory_stats · memory_consolidate · memory_export · memory_forget · memory_relate · memory_extract_session · memory_observe

</details>

<details> <summary><b>Knowledge graph (6)</b></summary>

memory_graph · memory_graph_index · memory_graph_stats · memory_concepts · memory_associate · memory_context_build

</details>

<details> <summary><b>Episodic memory & skills (4)</b></summary>

memory_episode_save · memory_episode_recall · memory_skill_get · memory_skill_update

</details>

<details> <summary><b>Reflection & self-improvement (7)</b></summary>

memory_reflect_now · memory_self_assess · self_error_log · self_insight · self_patterns · self_reflect · self_rules · self_rules_context

</details>

<details> <summary><b>Temporal knowledge graph (4)</b></summary>

kg_add_fact · kg_invalidate_fact · kg_at · kg_timeline

</details>

<details> <summary><b>Procedural memory (3)</b></summary>

workflow_learn · workflow_predict · workflow_track

</details>

<details> <summary><b>Pre-flight guards & automation (8)</b></summary>

file_context (pre-edit risk scoring) · learn_error (auto-consolidating error capture) · session_init / session_end · ingest_codebase (AST, 9 languages) · analogize (cross-project analogy) · benchmark (regression gate)

</details>

Full JSON schemas: python -m total_agent_memory.cli tools --json or open the dashboard at localhost:37737/tools.

---

Benchmarks — how it compares

Everything below is retrieval: does the memory surface the passage that contains the answer, in the top-K? That is the part this project owns — answer quality is bounded above by it, and it can be graded with no LLM in the loop, which makes the numbers deterministic, free, and reproducible on your machine.

Two things to read them honestly:

- These are the default fast profile — FastEmbed, no reranker, no LLM anywhere in the path. That is what you get after install.sh, not a tuned configuration. - Every runner passes record_usage=False. Recall.search normally bumps recall_count, and the scorer adds `recall_boost = min(0.3, recall_count × 0.05)` — so before v13, each re-run against the same database scored higher than the last, partly measuring its own history. A clean run and a re-run are now byte-identical.

Competitor comparison

We're not replacing chatbot memory — we're occupying the coding-agent + MCP + local niche.

On competitors' benchmark numbers. mem0 now publishes 92.5 on LoCoMo and 94.4 on LongMemEval. Those are end-to-end accuracy with their own generator, judge and prompts — not comparable to the retrieval numbers above, and not independently reproducible without their stack. We publish retrieval because the runner, the corpus and the gold labels are all public and you can re-run them on your laptop without an API key. Where a project has not published on a benchmark, we write "—" rather than inventing a number.

Full side-by-side with pricing, latency, accuracy, "when to pick each" → docs/vs-competitors.md.

---