Total Agent Memory

Search ALL memory: decisions, solutions, facts, lessons from ALL past sessions. 6-stage pipeline: FTS5+BM25 → semantic → fuzzy → graph → (optional) CrossEncoder → (optional) MMR. Default: hybrid mode (BM25 + semantic + RRF). Use BEFORE starting any task. v11.0: routes to fast hot path when MEMORY_MODE=fast (default). Use memory_search_fast / memory_explain_search for explicit fast routing.

Browse session history. sessions_ago=N for 'N sessions ago', session_number=1 for first session, date_from/date_to for date ranges.

Build local passage indexes before evidence searches. Repeat using next_after_id until remaining=0.

Generate and verify a cited answer using the configured reasoning LLM. Evidence carries recording dates; when records about the same subject disagree, the latest one gives the current value and the answer names the value it replaced. First runs negative retrieval: a contradiction-seeking second search; a score >= 0.60 hands both sides to the reader and answers with a caveat (MEMORY_CONTRADICTION_POLICY=abstain refuses instead), 0.30-0.60 answers with a caveat (see `negative`); MEMORY_CONTRADICTION_SCORER=jev scores the pairs with TypeSafe's Jev instead of the LLM. Up to one missing-relation retrieval and eight LLM calls including inversion retry and bounded quote repair. Explicit project required. Citation offsets refer to returned evidence content. Ordinary recall remains local.

Save knowledge explicitly. Types: decision (MUST include WHY in context), solution, lesson, fact, convention. Saving the same words again (case and punctuation aside) replaces the stored record, so it carries the latest date; any other text, including a changed value, is stored as a new record. v10: a quality gate scores the record before save; below-threshold records are rejected with a `rejected_by_quality_gate: true` response (override with MEMORY_QUALITY_GATE_ENABLED=false). Use `importance` to surface critical decisions at recall time (boosts the final RRF score). v11.0: routes to fast hot path when MEMORY_MODE=fast (default). Use memory_save_fast for explicit fast routing.

Update existing knowledge. Replaces the record `id`, or the best match for `find` (within `project` when given): supersedes it and creates a new version.

Memory statistics with health metrics: sessions, knowledge by type/project, retention zones (active/archived/consolidated), stale records, storage size, config, write path (embedding backfill queue, outbox intents, swallowed errors by component over 24h, importance budget clamps).

Takes no parameters.

Find and merge duplicate/similar knowledge records. Keeps the longest version, supersedes shorter duplicates. Reduces noise in recall results.

Export all knowledge as JSON for backup or migration. Includes knowledge, sessions, relations and the agent action log.

Apply retention policy: archive stale records (>180d, never recalled, low confidence), purge very old archived records (>365d), prune the agent action log past TAM_ACTION_LOG_RETENTION_DAYS. Keeps memory clean.

v10 — Render the per-project wiki digest (top decisions, active solutions, conventions, recent changes) as Markdown. Pass `project` to refresh one wiki, omit it to refresh all active projects. Files land in <MEMORY_DIR>/wikis/<project>.md and are deterministic (no LLM call).

Activity report for a project (or all projects) over a period: today (period=day), this week (week, ISO Monday-Sunday), this month (month), all time (all) or custom since/until dates; offset=-1 gives the previous day/week/month ('last week'). Sections: summary numbers with deltas against the previous equal period, key decisions with their WHY, solutions and fixes, errors with recurring patterns and lessons, open next steps and pitfalls from session summaries, most touched files, entities/technologies, and a day-by-day timeline. Every item carries source IDs (#id -> memory_get). Built deterministically from stored records, no LLM; include_llm_summary=true adds an optional paragraph from the configured LLM. Periods use the local timezone (or tz). save=true writes the Markdown to <memory dir>/reports/<project>/<period>-<date>.md. Use it when the user asks what happened, for a status/progress report, a weekly summary or a retrospective.

Batched fetch by ID — complement to memory_recall(mode='index'). Returns full content for ONLY the IDs the caller chose after inspecting an index. Typical 3-layer flow: recall(mode='index') → pick IDs → memory_get(ids=[...]).

View version history for a knowledge record. Shows the chain of superseded versions (newest → oldest), enabling time-travel through knowledge evolution.

Delete a knowledge record. By default a soft delete: the record leaves search results and vectors but stays in the database. hard=true erases it for good, with its earlier versions, derived rows and its text in the raw call log (use for personal data or anything that must not be kept).

Create a typed relation between two knowledge records. Enriches graph expansion in Tier 4 search. Types: causal, solution, context, related, contradicts.

Search knowledge by tag. Returns all active records with matching tag (partial match). Useful for categorical browsing.

Get pending session transcripts for knowledge extraction. Previous sessions are auto-captured on exit. Use action='list' to see pending, 'get' to read transcript, then save knowledge via memory_save, then 'complete' to mark as processed.

Log an error/failure for pattern analysis. Call AUTOMATICALLY when: bash command fails, wrong assumption discovered, API returns error, config issue found, loop detected, or any mistake occurs. System detects patterns (3+ same category) and suggests insights.

Manage insights from error patterns (ExpeL-style). Actions: add (create, importance=2), upvote (+1), downvote (-1, auto-archive at 0), edit, list, promote (to rule when importance>=5 AND confidence>=0.8). Call 'add' when pattern detected. Call 'upvote' when insight confirmed again.

Manage behavioral rules (SOUL). Rules are promoted insights that shape agent behavior. Actions: list, fire (record relevance), rate (success=true/false), suspend, activate, retire, add_manual, followed (surface_id from self_rules_context(query=...): was the rule followed?), report (follow-rate effectiveness with Wilson CIs, measurement only). success_rate = success / (success + fail). Auto-suspend: 5+ ratings and the 95% upper bound of success_rate < 0.4.

Analyze error patterns and self-improvement stats. Views: error_patterns (frequency, repeating 3+), insight_candidates (ready for promotion), rule_effectiveness (success rates, stale rules), improvement_trend (weekly errors), full_report (all). Call periodically to track improvement.

Save a verbal self-reflection (Reflexion pattern). Call after completing a task or encountering difficulty. NOT for errors (use self_error_log). For meta-observations about strategy, approach effectiveness, process improvements.

Get active behavioral rules for current session. Call at SESSION START to load rules. Returns rules filtered by project and scope. v8.0: pass `phase` to lazy-load rules relevant to current task phase — core rules (no phase tag) + rules tagged phase:<X>. Cuts prompt tokens ~70%. After task completion, rate rules: self_rules(action='rate', id=X, success=true/false).

Attach or remove a phase scope on a rule (v8.0 lazy rule loading). Tag-based: manages 'phase:<X>' on the rule's tags. phase=null clears the phase tag (rule becomes core — applies to every phase). Valid phases: van, plan, creative, build, reflect, archive.

Save a lightweight observation (auto-capture). No dedup, no ChromaDB — fast and cheap. Use for tracking file changes, tool usage, and session activity. Observations auto-cleanup after 30 days.

Associative recall — brain-like spreading activation through knowledge graph. Finds memories through concept resonance, not keyword search. In 'composition' mode, finds minimum set of memories covering all needed concepts.

Query the unified knowledge graph. Returns neighborhood of a node: connected rules, skills, memories, concepts, entities.

List or search concepts in the knowledge graph.

Save an episode — narrative of WHAT HAPPENED and HOW. Not just facts, but the journey: what was tried, what failed, what worked.

Find past episodes (experiences). Search by concepts, outcome, project, or impact.

Find skills matching a trigger. Skills are learned procedures — HOW to do things.

Record skill usage or refine a skill. Updates success rate and metrics.

Self-assessment: how competent am I in given domains? Shows level, confidence, blind spots.

Build optimal context for a query. Combines: spreading activation + knowledge graph + episodes + skills + self-model. The 'brain thinking' tool.

Run reflection (the 'sleep' process). Consolidates knowledge, finds patterns, generates skill proposals, updates self-model.

Reindex CLAUDE.md rules and skills into the knowledge graph. Run after modifying CLAUDE.md or adding new skills.

Knowledge graph statistics: nodes, edges, communities, top concepts, health metrics.

Takes no parameters.

Record a temporal fact assertion (subject, predicate, object). Supersedes any prior assertion with same (s,p) and different object — full history is preserved. Use for evolving architectural decisions.

Close a currently-valid fact assertion. History is retained.

Point-in-time query: return fact assertions valid at `timestamp` (ISO 8601). Omit timestamp for currently-valid facts.

Full chronological history of assertions for a subject.

Record a learned workflow (named sequence of steps) for future reuse.

Predict outcome (success probability, avg duration) for a workflow by id OR by trigger keyword. Uses Laplace-smoothed success rate.

Record a workflow execution outcome. Outcome ∈ {success|failure|partial|aborted}. Aggregates update automatically.

BEFORE editing a file, call this to surface past errors, lessons, and related rules for that file path. Returns risk_score ∈ [0, 1].

Structured error capture: file, error, root_cause, fix, pattern. After N (default 3) errors share the same pattern, a prevention rule is auto-synthesized into the rules table.

At session start: return the most recent unconsumed end-of-session summary with highlights / pitfalls / next_steps.

End-of-session capture: summary + highlights + pitfalls + next_steps so the next session can resume cleanly. Set auto_compress=true to have the LLM generate the missing summary/next_steps/pitfalls from stored session artifacts (or from an optional `transcript`).

Parse a file or directory into semantic AST chunks (functions, classes, methods) across 8 languages. Returns chunk count + sample.

Find past solutions/lessons from OTHER projects whose feature set overlaps with the given problem text (Jaccard similarity).

Run the eval harness: recall_at_k, prevention_rate, latency percentiles. Loads scenarios from evals/scenarios/*.json by default.

v11.0: same as memory_save but routes through the fast hot path (skip_quality=True, no LLM, no async-blocking). Use when you want to bypass the v10 quality gate without flipping the env flag.

v11.0: like memory_recall but with rerank=False, diverse=False forced. Deterministic fast path — zero LLM, FastEmbed-only.

v11.0: same as memory_search_fast but returns a per-tier breakdown (fts/semantic/graph/fuzzy/hyde with raw scores, the merged RRF list, rerank_applied flag, embedding_space). Use to debug why a record did or didn't surface for a query.

v11.0: pre-load FastEmbed model and open the vector store, so the first save/search after process start doesn't pay model-load latency.

Takes no parameters.

v11.0: dump in-process telemetry counters (search_total_ms, embed_ms, fts_ms, vector_ms, llm_calls, network_calls) plus persistent embedding_cache stats. Use to verify the fast hot path stays clean.

Takes no parameters.

v11.0: drop and rebuild the SQLite FTS5 virtual table from `knowledge` rows. Useful after migrations or content_type column changes that the FTS triggers didn't see. Returns {rebuilt: int}.

Takes no parameters.

v11.0: re-encode every record (or every record in a given embedding space) and update the binary + float32 vectors. Idempotent. Pass embedding_space='code' to refresh only code rows after switching the code embedder. Returns {rebuilt: int, skipped: int}.

v11.0 Phase 8: run the LongMemEval-style recall+prevention scenario suite (loaded from evals/scenarios/) against the live store. Forces MEMORY_MODE=fast by default. Returns {scenarios_total, scenarios_passed, recall_at_5, recall_at_10, latency_ms, mode, llm_calls_during_eval, network_calls_during_eval}.

v11.0 Phase 8: generic recall benchmark on a dataset path or a small built-in fixture. Same payload shape as memory_eval_locomo.

v11.0 Phase 8: temporal recall using temporal_kg + temporal_filter. Returns {status: 'not_implemented', ...} when modules are missing.

v11.0 Phase 8: verifies entity_dedup canonicalization is stable across repeated saves of variant tag spellings.

v11.0 Phase 8: runs contradiction_detector against a labelled fixture. Requires balanced/deep mode (LLM). Returns {status: 'not_implemented', ...} if module is unavailable.

v11.0 Phase 8: large-context recall scenario. Saves N records and queries them at the tail. Reuses eval_harness scenarios tagged 'long_context' if present.

v8.0: classify task into L1-L4 complexity + suggested phases.

v8.0: start a task in `van` phase (auto-classifies level if missing).

v8.0: advance a task to the next phase.

v8.0: list all phases of a task in chronological order.

Persist one user prompt into the `intents` table (same source as the UserPromptSubmit hook). Use when programmatically seeding intents — the hook covers normal interactive usage. Dedupes same prompt within 5 min per session.

List recent user prompts from the intents table, newest first. Filter by project and/or session. Max 500 rows.

Substring search over user prompts (LIKE). Returns newest match first. Useful for 'what did I ask about X' without mining transcripts.

v8.0: save a structured architectural decision (options + criteria matrix + rationale + discarded). Adds `structured` tag and a JSON blob in context. Use for Creative-phase outputs; plain type=decision memory_save still works.

v11.0 W1-B: IRCoT-style iterative retrieval. Decomposes the query into sub-questions, retrieves per sub-question, and asks a planner LLM whether more retrieval is needed. Best for multi-hop questions. Returns unified evidence + provenance per iteration.

v11.0 W1-C: deterministic temporal reasoning — Allen interval relations, duration arithmetic (days/weeks/months/years), and natural-language date normalization (en + ru). Pass op=relation|duration_between|normalize.

v11.0 W1-F: resolve a mention to its canonical entity within a project+type. Cross-session coreference via name/alias index + embedding cosine. Returns canonical_id, matched_via, and is_new flag. Pronouns return -1.

v11.0 W2-G: report the consolidation daemon state — per-project last-run, active locks, recent activity. Use to verify the idle-project worker is making progress without interfering with active work.

Takes no parameters.

Record the conclusion of a codebase exploration together with the SHA-256 of every file read to reach it. Call it after answering a structural question by reading files (how X is wired, where Y is decided). Paths are stored relative to `root` (default: the server's working directory); files outside root are refused. Up to 64 files of at most 32 MB each. Recording the same question again for the project replaces the earlier memo.

Before re-reading files to answer a codebase question, look up earlier exploration conclusions. Results are ranked by question similarity; each carries status 'fresh' (every source file is byte-identical to when the conclusion was recorded: reuse it) or 'stale' (changed_files / missing_files list what to re-read).