Store one or more memories in persistent cognitive memory.

WHEN TO USE: Call proactively whenever the conversation reveals something worth remembering — decisions, preferences, facts about people, project context. Do NOT store ephemeral task details, code snippets, or git-derivable info.

SINGLE: remember(text="User prefers dark mode", domain="preference", importance=0.7) BATCH: remember(memories=[{"text": "Alice is DevOps lead", "domain": "people"}, ...]) DRAFT: remember(summary="...long end-of-session summary...") — v0.8.0+ engine atomizes the summary into linked semantic facts; useful for the end-of-session auto-capture pattern.

IMPORTANCE: 0.8-1.0 critical decisions | 0.5-0.7 useful context | 0.3-0.5 background

Args: text: Memory text (for single memory). Be specific and searchable. memory_type: "semantic" (facts), "episodic" (events), "procedural" (how-to). importance: 0.0-1.0. Higher = remembered longer. domain: "work", "preference", "architecture", "people", "infrastructure", "health", "finance", "general". source: "user", "inference", "document", "system". valence: Emotional tone (-1.0 to 1.0). 0.0 neutral. metadata: Optional key-value pairs. namespace: For per-project isolation. certainty: Confidence 0.0-1.0. emotional_state: joy, frustration, excitement, concern, neutral. memories: List of memory dicts for batch. summary: For draft mode — long summary that the engine atomizes. idempotency_key: v0.10 engine — makes the write exactly-once: retrying with the same key + same text returns the SAME rid with no second write; same key + different text is an error. Engine-embedder (bundled) backend only. On batch, the key scopes per item as "{key}:{index}" if the atomic batch path is unavailable.

Search memories by semantic similarity, or refine low-confidence results.

MODES:

• Search (default): recall("project architecture decisions")

• Refine: recall("PostgreSQL vs MySQL decision", refine_from="database choice", refine_exclude=["rid1"]) (Relevance feedback moved to memory(action="feedback") in v0.10 — recall is now purely read-only.)

WHEN TO USE: conversation start (summarize the user's first message); when the user references past decisions, people, preferences, or "last time"; when unsure about something the user assumes you know. Refine when first confidence < 0.5. After USING a recalled memory, reinforce it via memory(action="feedback", rid=..., feedback="relevant"). For "what is the CURRENT/latest X", prefer memory(action="chain_head") — similarity favors the most-similar revision, not the newest.

QUERY: one short natural-language sentence (5-10 words), NOT a keyword list — keyword stuffing degrades quality. One focused question per call; separate calls for separate topics.

TRUST SIGNALS: each hit's why_retrieved may carry staleness warnings ("aged", "rarely confirmed", "superseded by a newer record"). Treat flagged hits as weak evidence — prefer fresher results or chain_head, and note the flag if you act on one anyway.

Args: query: Short natural language sentence (5-10 words). NOT a keyword list. top_k: Max results (default 10). 3-5 for focused, 10-20 for broad. memory_type: Filter: "semantic", "episodic", "procedural". domain: Filter: "work", "preference", "architecture", "people", etc. source: Filter: "user", "inference", "document", "system". namespace: Filter by namespace. include_consolidated: Include merged memories. include_superseded: v0.10 — recall EXCLUDES superseded records by default (current-by-default). Set True only for history / archaeology over a revision chain. expand_entities: Use knowledge graph boosting (default True). refine_from: Original query text to refine from. query becomes the refinement. refine_exclude: Memory IDs to exclude when refining.

Permanently forget (tombstone) one or more memories.

WHEN TO USE: When the user explicitly asks to forget something, or when a memory is clearly wrong and correction isn't appropriate. Prefer correct over forget when the memory just needs updating.

Args: rid: Single memory ID to forget. rids: List of memory IDs to forget (batch mode).

Correct an existing memory in-place with a revision-history entry (engine v0.7.20+, Issue #47).

WHEN TO USE: When the user corrects a recalled fact.

• "Actually, we're using Python 3.12, not 3.11" → correct the memory.

Preserves history via an append-only revision entry keyed on reason. Entity relationships stay attached to the same rid (in-place mutation, not a tombstone+new-rid dance).

Args: rid: The memory ID to correct. reason: Required — why the correction was made. Non-empty. Recorded on the revision-history entry so future recall + audit can reconstruct why the memory changed. new_text: Optional new text (pass None to keep existing). new_importance: Optional updated importance (0.0-1.0). new_valence: Optional updated valence (-1.0 to 1.0). metadata_merge: Optional dict to merge into existing metadata (None = keep as-is).

Run incremental cognitive maintenance — processes a small batch per call.

DESIGNED TO BE CALLED OFTEN: Each call processes ~5 memories (configurable). Running regularly (e.g. at end of conversation) gradually maintains the entire database without blocking. Safe to call frequently.

MODES:

• Default: incremental think() — consolidation + conflict scan + (optional) pattern mining on a small batch.

• maintenance_cycle=True: run the v0.9.0 autonomous-hygiene "sleep cycle" — think + burn-down-conflicts + prune-triggers + recalibrate-importance + backfill-entities + auto-relate (+ optional split_oversized + repair_artifacts).

• last_cycle_only=True: just fetch the last persisted maintenance-cycle summary (read-only, no work performed).

• maintenance_op="backfill_entities"|"rebuild_vec_index"|"rebuild_graph_index": run ONE targeted index-maintenance op and return. (Moved here from stats in v0.10 so stats could become read-only.)

Args: run_consolidation: Merge similar memories (default on). run_conflict_scan: Detect contradictions (default on). run_pattern_mining: Mine cross-domain patterns (default off, slow). consolidation_time_window_days: Only consolidate memories within this window (default 7 days). consolidation_limit: Batch size — max memories to process per call (default 5). Keep small for fast returns. maintenance_cycle: Run the full autonomous hygiene cycle instead. last_cycle_only: Just fetch the last cycle summary (read-only). dry_run: For maintenance_cycle — preview without persisting changes. burn_down_conflicts / prune_triggers_too / max_pending_triggers / recalibrate_importance / backfill_entities / auto_relate_in_cycle / max_auto_relate_edges / split_oversized / split_min_chars / repair_artifacts: Maintenance-cycle knobs.

Manage individual memories — get, list, search, update importance, archive, hydrate, relevance feedback, fetch a chain-shaped namespace's head, or query revision history.

ACTIONS:

• "get": Retrieve a single memory by rid.

• "list": Browse memories with filters.

• "search": Keyword substring search.

• "update_importance": Change a memory's importance score.

• "archive": Move to cold storage.

• "hydrate": Restore archived memory.

• "feedback": v0.10 — relevance feedback on a recalled memory (needs rid + feedback="relevant"|"irrelevant"). Call after USING a recalled memory; it tunes future retrieval. (Moved here from recall, which is now read-only.)

• "chain_head": The CURRENT value of a chain-shaped namespace (narrative / decision / config chains). Use this — not recall — for "what is the current/latest X": similarity search favors the most-similar revision, chain_head returns the newest.

• "history": v0.8.0 — revision history for a single rid (needs rid).

Args: See action docs above. New args: namespace: Required for chain_head — the chain-shaped namespace. rid: Required for history/feedback — the record acted on. feedback: For feedback — "relevant" or "irrelevant". feedback_query: For feedback — the query that surfaced the memory. feedback_score / feedback_rank: For feedback — retrieval context.

Knowledge graph operations — entity relationships, memory↔entity links, record-to-record links, co-occurrence auto-relate, and link-expanded recall.

ACTIONS:

• "relate": Entity↔entity relationship (legacy).

• "edges": Get all relationships for entity.

• "link": Link a memory (rid) to an entity (legacy).

• "search": Find entities by pattern.

• "profile": Rich entity profile.

• "depth": How deeply the system knows an entity.

• "auto_relate": v0.8.0 — co-occurrence-driven edge backfill. Set dry_run=False to persist.

• "record_link": v0.9.0 — add a record-to-record link (needs source_rid + target_rid + link_type).

• "record_unlink": v0.9.0 — remove a record-to-record link.

• "linked_records": v0.9.0 — traverse links from rid (direction = "outbound" | "inbound" | "both", optional link_type filter).

• "recall_with_links": v0.9.0 — semantic recall with N-hop link expansion.

Args: action: One of the actions above. entity / target / relationship / weight / rid / pattern / limit / days / namespace: Legacy entity-graph args. source_rid / target_rid / link_type: For record_link / record_unlink. direction: For linked_records — "outbound" / "inbound" / "both". dry_run: For auto_relate — preview without persisting. max_edges: For auto_relate — cap edges proposed/created. query: For recall_with_links — natural language search. top_k: For recall_with_links — max seed results. expand_links: For recall_with_links — hop budget for traversal.

Manage memory conflicts (contradictions) — list, resolve, dismiss, reclassify, or batch-burn-down the unambiguous ones (v0.8.0+).

ACTIONS:

• "list": List conflicts. Optional status filter.

• "get": Get single conflict by conflict_id.

• "resolve": Resolve with strategy: "keep_a"/"keep_b"/"keep_both"/"merge"/"dismiss".

• "reclassify": Reclassify conflict type.

• "auto_resolve": v0.8.0 — burn down unambiguous conflicts in one pass. Set dry_run=False to actually persist.

Args: action: "list", "get", "resolve", "reclassify", "auto_resolve". conflict_id / status / strategy / winner_rid / new_text / resolution_note / new_type / limit: see action docs above. dry_run: For auto_resolve — preview without persisting.

Manage proactive triggers + v0.8.0 bounded-backlog pruning.

ACTIONS:

• "pending": Get pending triggers (default).

• "history": View past triggers.

• "acknowledge": Mark trigger as seen.

• "deliver": Mark as shown to user.

• "act": Mark as acted upon.

• "dismiss": Dismiss as irrelevant.

• "prune": v0.8.0 — expire overdue triggers + evict oldest when over max_pending. Set dry_run=False to actually persist.

Args: action: One of the actions above. trigger_id: Required for acknowledge/deliver/act/dismiss. trigger_type: Filter by type (for pending/history). limit: Max results. dry_run: For prune — preview without persisting. max_pending: For prune — soft cap on the pending backlog (default 64).

Session lifecycle — start, end, history, active check, stale cleanup, and the v0.9.0 boot-time digest.

ACTIONS:

• "start": Begin a new session. Returns session_id.

• "end": End a TRACKED session (needs session_id). Returns stats. This closes session bookkeeping — it does NOT capture memories.

• "capture": Segment a free-text session summary into atomic candidate memories (needs summary; NO session_id — it operates on the text, not on tracked-session state). Returns drafted rids. Use at end of substantial work so the session leaves a trace.

• "history": View past sessions.

• "active": Check if there's a running session.

• "abandon_stale": Clean up orphaned sessions older than abandon_stale_hours.

• "digest": One-call boot-time briefing (v0.9.0) — narrative chain head, open decisions/conflicts/triggers, top stale memories. Call this at conversation start instead of N separate recalls. Set include_gaps=True to fold known-unknowns (frequently-asked, poorly-answered queries) into the briefing — the active-learning loop. Set scope to filter content aggregates to one namespace for a per-tenant digest.

Args: action: "start", "end", "capture", "history", "active", "abandon_stale", "digest". session_id: For end. namespace: Memory namespace. client_id: Client identifier. metadata: For start — optional dict. summary: For end — optional closing note. For capture — REQUIRED, the session summary to segment into memories. domain: For capture — domain stamped on drafted memories. limit: For history. abandon_stale_hours: For abandon_stale — max age in hours. narrative_namespace: For digest — namespace for the narrative chain. scope: For digest — filter content aggregates to one namespace (per-tenant isolation); omit for a whole-DB digest. include_gaps: For digest — fold top knowledge gaps into the briefing. max_gaps: For digest — cap on gaps surfaced when include_gaps=True. max_decisions / max_conflicts / max_triggers: For digest — surface caps. snippet_chars: For digest — text-snippet length per item.

Find stale or upcoming memories based on time.

ACTIONS:

• "stale": Important memories not accessed recently. Good for maintenance.

• "upcoming": Memories with approaching deadlines/events. Good for proactive alerts.

Args: action: "stale" or "upcoming". days: Inactivity threshold (stale) or look-ahead window (upcoming). limit: Max results. namespace: Optional filter.

Procedural memory — learn, surface, and reinforce strategies.

ACTIONS:

• "learn": Store a procedure (needs text). What worked in a specific context.

• "surface": Find relevant procedures (needs query). Returns ranked by effectiveness.

• "reinforce": Update effectiveness (needs rid + outcome 0.0-1.0).

EXAMPLES:

• procedure(action="learn", text="For this repo, always run tests before committing", domain="work")

• procedure(action="surface", query="how to handle code review in this repo")

• procedure(action="reinforce", rid="abc", outcome=0.9)

Args: action: "learn", "surface", "reinforce". text: Procedure description (for learn). query: What you're about to do (for surface). rid: Procedure ID (for reinforce). domain: Task domain. task_context: What kind of task (for learn). effectiveness: Initial effectiveness 0.0-1.0 (for learn). outcome: How well it worked 0.0-1.0 (for reinforce). top_k: Max results (for surface). namespace: Namespace.

Substitution categories for conflict detection — list, inspect, teach, or reset.

ACTIONS:

• "list": Show all categories with member counts.

• "members": Show members of a specific category (needs category_name).

• "learn": Teach new members (needs category_name + members as [[token, confidence], ...]).

• "reset": Reset category to seed state (needs category_name).

EXAMPLES:

• category() → list all categories

• category(action="members", category_name="databases")

• category(action="learn", category_name="databases", members=[["tidb", 0.35]])

• category(action="reset", category_name="editors_tools")

Args: action: "list", "members", "learn", "reset". category_name: Required for members/learn/reset. members: For learn: [[token, confidence], ...]. source: For learn: "llm_suggested", "user_confirmed", "seed".

AI personality traits derived from memory patterns.

ACTIONS:

• "get": Get current personality profile. Use recompute=True to refresh.

• "set": Set a trait manually (needs trait_name + score).

Traits: warmth, depth, energy, attentiveness (0.0-1.0).

Args: action: "get" or "set". trait_name: For set: warmth, depth, energy, attentiveness. score: For set: 0.0-1.0. recompute: For get: re-derive from memory patterns first.

Engine statistics, health check, learned weights, privacy/leak audit, and skill substrate counts. Read-only — index maintenance moved to think(maintenance_op=...) in v0.10.

ACTIONS:

• "stats": Detailed memory statistics (default).

• "health": Quick health check with latency.

• "weights": Show adapted recall scoring weights.

• "audit_leak": v0.8.0 windowed leak-candidate audit — surfaces recent records that may have leaked sensitive content. Use for privacy review.

• "skill_outcomes": v0.9.0 — total skill outcomes recorded in the durable timeline.

Args: action: One of the actions above. namespace: Filter for stats. max_rids: For audit_leak — max candidate rids to inspect.

Substrate-native agent skill catalog — define, surface, record outcomes.

Skills are structured catalog entries (skill_id, applies_to, body, type) — different from loose how-to memories (use procedure for those). Writes go to the skill_substrate namespace so every yantrikdb consumer (this MCP, yantrikdb-hermes-plugin, Lane B SDK, WisePick) sees the same catalog.

Schema-validated at write time:

• skill_id: lowercase dot-separated segments, e.g. "workflow.git.commit_clean"

• body: 50–5000 chars

• applies_to: 1–10 lowercase_underscore identifiers (no hyphens)

• skill_type: one of procedure | reference | lesson | pattern | rule

ACTIONS:

• "define": Create a skill (needs skill_id, body, skill_type, applies_to).

• "surface": Find relevant skills (needs query). Returns ranked by score.

• "outcome": Append a use outcome (needs skill_id, succeeded).

• "get": Fetch a single skill by id.

• "list": Catalog browse (filter by applies_to / skill_type).

EXAMPLE: skill(action="define", skill_id="workflow.git.commit_clean", body="Before commit: run pytest + lint...", skill_type="procedure", applies_to=["git", "release"]) — then surface(query=...) before similar work, and outcome(skill_id=..., succeeded=True/False) after using one.

Args: action: "define", "surface", "outcome", "get", "list". skill_id: Dot-separated id (for define/get/outcome). body: Skill body, 50–5000 chars (for define). skill_type: procedure|reference|lesson|pattern|rule (for define). applies_to: Non-empty identifier list ≤10 entries (for define; optional filter for surface/list). triggers: Optional list of trigger phrases (for define). on_conflict: "reject" (default) or "replace" if skill_id exists. version: Optional semver-shaped version string. supersedes: Optional skill_id this one replaces. query: Natural-language search (for surface). top_k: Max results for surface. succeeded: Outcome boolean (for outcome). note: Optional outcome note. limit: Max results for list.

Surface knowledge gaps — frequently-asked, poorly-answered queries (v0.9.0 engine demand log).

The substrate logs every recall and tracks how often each query is asked

• what top scores it surfaces. knowledge_gaps() returns the queries that are asked often but answered poorly — the substrate's "known unknowns". Use this to drive proactive learning: when the agent sees a gap, it can ask the user, fetch info, or note the limitation.

Args: min_count: Only surface queries asked at least this many times. max_avg_top_score: Only surface queries whose best recall score averages below this (lower = poorer answer). limit: Max gaps to return.

Bounded encrypted working-memory ring buffer for raw conversation turns (v0.9.0 engine conversation primitive).

Unlike remember (which stores extracted semantic memories), this stores verbatim turns — useful for short-horizon working memory, e.g. "what exactly did the user say two messages ago". The ring is bounded per namespace; oldest turns evict when max_turns is exceeded.

ACTIONS:

• "record": Append a turn (needs role + content).

• "recent": Retrieve last N turns, oldest-first.

• "clear": Drop the buffer for a namespace.

Args: action: "record" | "recent" | "clear". namespace: Ring buffer namespace (separate buffers per agent / topic). role: "user" | "assistant" | "system" | "tool" — caller's choice. content: The verbatim turn text. max_turns: Ring size at record time (default 10). limit: How many recent turns to return.

Substrate-backed task / chore store (v0.9.0 engine).

A thin general-purpose to-do tracker baked into yantrikdb — survives sessions, lives next to memories so future agents see open tasks at session_digest time.

ACTIONS:

• "add": Create a task (needs title; optional priority + parent_id).

• "get": Fetch one task by id.

• "list": List tasks in a namespace, optionally filtered by status.

• "update": Update status and/or priority (needs task_id).

• "delete": Delete a task (needs task_id).

PRIORITY: "low" | "medium" | "high" — priority-ordered in list. STATUS: typically "open" | "doing" | "done" | "blocked".

Args: action: "add" | "get" | "list" | "update" | "delete". namespace: Per-project / per-agent isolation. title: Task description (for add). priority: "low" | "medium" | "high" (for add / update). parent_id: Optional parent task id (for add — sub-task tree). task_id: Task id (for get / update / delete). status: Filter (for list) or new value (for update).