Total Agent Memory Client
TypeScript client for total-agent-memory (server v8.0+) β local-first MCP memory layer for AI coding agents
Ask AI about Total Agent Memory Client
Powered by Claude Β· Grounded in docs
I know everything about Total Agent Memory Client. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
@vbch/total-agent-memory-client
TypeScript / JavaScript client for total-agent-memory β the local-first MCP memory layer for AI coding agents.
New in 0.2.0 (server v8.0+ required): structured decisions with per-criterion scoring, an L1-L4 task state machine (
classifyTask/taskCreate/phaseTransition), progressive-disclosure retrieval (mode: "index"+memoryGet) that cuts typical recall tokens by 80-90%, intent capture, phase-scoped rules, LLM-compressedsessionEnd, and inline<private>β¦</private>redaction reporting.
Why use this? If you're building in Node.js, Bun, Deno, or browsers and you want persistent, graph-aware memory that learns how you work, not just what you said β this is your client. 100% local by default. Temporal facts. Procedural workflows. Cross-project analogy. See the engine feature matrix vs mem0 / Letta / Zep / Supermemory.
Install
npm i @vbch/total-agent-memory-client
# peerless β bundles @modelcontextprotocol/sdk
You also need the server running. One-line install:
curl -fsSL https://raw.githubusercontent.com/vbcherepanov/total-agent-memory/main/install.sh | bash
Quick start (stdio β local MCP subprocess)
import { connectStdio } from "@vbch/total-agent-memory-client";
const memory = await connectStdio();
// resume where you left off
const { summary, next_steps } = await memory.sessionInit("my-project");
// remember a decision
await memory.save({
type: "decision",
content: "Chose pgvector over ChromaDB for multi-tenant RLS.",
context: "Why: single DB, per-tenant row-level security.",
project: "my-project",
tags: ["database"],
});
// recall it later (or from a different process, or next month)
const hits = await memory.recallFlat({
query: "vector store choice",
project: "my-project",
limit: 5,
});
Quick start (HTTP β remote gateway)
Works against the dashboard HTTP gateway (total-agent-memory v7.1+):
import { connectHttp } from "@vbch/total-agent-memory-client";
const memory = connectHttp({
baseUrl: "http://127.0.0.1:37737",
token: process.env.MEMORY_TOKEN, // optional
});
const stats = await memory.stats();
console.log(stats.knowledge.active, "records across", Object.keys(stats.by_project).length, "projects");
What you get over mem0 / Zep / Supermemory SDKs
| Capability | mem0 JS | Zep JS | Supermemory JS | this |
|---|---|---|---|---|
| Local-first (no network) | β | β | β | β stdio |
| Semantic + BM25 + graph hybrid | π‘ | β | β | β 6-tier |
Temporal facts (kg_at) | β | β | β | β |
Procedural memory (workflow_predict) | β | β | β | β |
Cross-project analogy (analogize) | β | β | β | β |
Pre-edit risk warnings (file_context) | β | β | β | β |
AST codebase ingest (ingest_codebase) | β | β | β | β |
| Strict TypeScript types for all tools | π‘ | π‘ | π‘ | β |
API surface
Session lifecycle
sessionInit(project)β resume previous session's summary + next stepssessionEnd({ summary, next_steps, pitfalls })
Core memory
save({ type, content, context?, project?, tags?, branch? })recall({ query, project?, limit?, rerank?, diverse?, β¦ })recallFlat(input)β flattened, RRF-sorted list
v7 tools
fileContext(path)β risk score + past-error warnings for a filelearnError({ file, error, root_cause, fix, pattern })β auto-consolidates into rules at Nβ₯3analogize({ query, exclude_project? })β cross-project pattern matchkgAddFact({ subject, predicate, object, valid_from? })β append-only temporal KGkgAt(timestamp)β point-in-time fact snapshotworkflowPredict(task_description)β procedural prediction with confidenceworkflowTrack(workflow_id, outcome)β close the loop after task completioningestCodebase({ path, languages? })β AST indexing via tree-sitter (9 langs)
v8 tools (requires server 8.0+)
classifyTask(description, project?)β L1-L4 classifier, returns suggested phases + confidencetaskCreate(taskId, description, level?)β open a task in the state machinephaseTransition(taskId, newPhase, artifacts?, notes?)β step throughvanβplanβcreativeβbuildβreflectβarchivetaskPhasesList(taskId)β full phase timeline for a tasksaveDecision({ title, options, criteria_matrix, selected, rationale })β structured decisions with per-criterion scoring, indexed for recallmemoryRecall({ mode: "index" })+memoryGet(ids, detail?)β progressive-disclosure retrieval: cheap index scan β targeted fetch. ~80-90% token savings on typical 20-hit queries vs.mode: "search", detail: "full".saveIntent/listIntents/searchIntentsβ captured user promptsruleSetPhase(ruleId, phase)β scope a rule to a task phase (ornullfor global)- Extended
sessionEnd({ auto_compress, transcript })β LLM-generated summary/next-steps from a raw transcript - Extended
MemorySaveResult.privacy_redacted_sectionsβ count of inline<private>β¦</private>sections stripped before storage
Progressive disclosure in practice
// Layer 1: cheap index scan (id + title + preview per hit, ~50 tokens each)
const idx = await memory.memoryRecall({
query: "database choice",
mode: "index",
limit: 20,
});
// Layer 2: agent picks what's worth the full body
const keepIds = (idx.index_results ?? []).slice(0, 3).map((r) => r.id);
const full = await memory.memoryGet(keepIds, "full");
Introspection
stats()β active knowledge, projects, storage, queuesbenchmark()β reproducible R@k + latency eval
Integrations
- LangChain JS β
examples/langchain-adapter.ts - Vercel AI SDK β wire
memory_saveas a tool in your agent loop - LlamaIndex TS β implement
BaseMemoryaroundsave/recallFlat - CrewAI / AutoGen (Python peers) β use the Python client directly
Privacy
This client spawns a local subprocess (stdio) or calls a locally-bound HTTP port.
No data is sent to any cloud service unless you configure the server to use one
(the default nomic-embed-text via Ollama is also fully local).
License
MIT. See LICENSE.
