total-agent-memory

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.

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

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

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

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.

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

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

Full chronological history of assertions for a subject.

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.

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

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.

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.

List or search concepts in the knowledge graph.

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

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.

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

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).

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.

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

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

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: verifies entity_dedup canonicalization is stable across repeated saves of variant tag spellings.

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: large-context recall scenario. Saves N records and queries them at the tail. Reuses eval_harness scenarios tagged 'long_context' if present.

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: 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.

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).

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.

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

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.

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.

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=[...]).

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

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.

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

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

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.

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.

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: 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}.

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.

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.

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

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

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 /reports//-.md. Use it when the user asks what happened, for a status/progress report, a weekly summary or a retrospective.

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.

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.

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

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

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

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.

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).

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.

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

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

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.

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/.md and are deterministic (no LLM call).

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

Attach or remove a phase scope on a rule (v8.0 lazy rule loading). Tag-based: manages 'phase:' 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.

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.

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.

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

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.

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.

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.

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:. Cuts prompt tokens ~70%. After task completion, rate rules: self_rules(action='rate', id=X, success=true/false).

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).

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

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

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

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.