FactMem

Store a durable fact worth remembering across sessions. A durable fact is a stable piece of knowledge about whatever this store is used for: its subjects, their attributes, their relationships, decisions, and context. Ignore ephemeral statements (current tasks, transient mood). Call this proactively whenever you learn something this store should keep. Capture is fast — the server stores the fact immediately. Entity extraction, domain classification, and cross-session reconciliation run in batch when you call consolidate. Capture frequently without slowing the conversation. Exact same-session duplicates are dropped immediately. Cross-session exact duplicates are also rejected during the next consolidation run — safe to capture the same fact from multiple conversations without polluting the knowledge graph.

Turn what has been captured into long-term knowledge. Copies new lines from named sources, extracts candidate facts from them, and integrates the pending facts: domains, entities, duplicates, contradictions, the knowledge graph. Call this to integrate pending facts into long-term knowledge. Good checkpoints: after capturing several facts, at a topic change, or before the conversation ends. Extract is capped at 50 of the oldest unexamined events per call; events_remaining in the result says how many wait. Pass all: true to take the whole backlog in one call, or limit: N for the oldest N.

Get everything known about a topic, combining search with entity relationship traversal. More comprehensive than search_knowledge — it follows entity connections outward: from a named subject to the things it relates to, and the facts about those in turn. Call this when you need the COMPLETE picture of a topic, subject, or domain rather than a specific fact — planning something involving a person, project or system, catching up on a subject, or answering an open-ended question about any of them. Prefer search_knowledge when you want one fact fast; prefer this when missing a connection would make your answer wrong.

Get everything known about a named thing — who or what it is, the facts about it, and how it connects to other things. A "thing" is any subject this store holds knowledge about: a person, an organisation, a project, a place, a product, a system — whatever the store is used for. This is the "tell me about X" tool. Call this WHENEVER a named thing is mentioned or alluded to and knowing it would improve your answer — including indirect references like "my manager", "the Helsinki office", "the payments service". Call it before advising on anything involving that thing, and before asking who or what something is — you may already know. Facts come back most relevant first, each flagged with is_subject. True means the fact is ABOUT this thing; false means it only mentions it. Treat the difference as real when you answer: "Alex's transfer was approved by Robin" is worth knowing when asked about Robin, but it is a fact about Alex, and reporting it as something you know about Robin would be wrong. Other relationship values are the same kind of role — this entity's part in this fact, free text, not a directed graph edge. Do not infer who did what to whom from the wording. If several entity rows share that name under different types (the extractor labelled one thing two ways), facts from all of them come back. Hyphens, underscores, and stray punctuation count as the same letters only when that does not join two names already stored as separate rows. If this store has no entity by that name, facts that mention the wording still come back (is_subject false) rather than an empty miss. found is whether an entity row exists, not whether anything is known.

Retrieve events from the current or a previous session. Returns the raw episodic record — messages, tool calls, tool results, and artifacts in sequence order. Use this to recall what happened earlier in a conversation (especially after context compaction), or to review a previous session.

List the knowledge domains this user's memory actually uses, and their subdomains. The set is not fixed — beyond the core domains it grows to fit the user, so it is worth asking rather than assuming. Call this before filtering a search by domain, before choosing a domain_hint for capture_fact, or when you want to know how this user's knowledge is organised. Rarely needed mid-conversation — search_knowledge and get_context work without it.

At the start of every conversation, before answering, call get_session_context unless you already loaded the memory://briefing resource. That call returns the same working briefing the resource would have injected. Tools-only clients never fetch resources. Also returns facts captured in this session that have not been consolidated yet. Call it before re-capturing a fact you may have already stored this session.

Get knowledge base statistics — how many facts are currently true, how many are held in total including superseded history, entity and domain counts, how facts are distributed across domains, and how much raw log can be reclaimed. Call this when the user asks what you know or remember about them, how much you have stored, or whether their memory is working. This answers "how much do you know", not "what do you know" — use search_knowledge, get_entity or get_context for actual recall. `embeddings` reports semantic-search coverage per model. An empty list means this store searches by keyword only, which is the default. A count well below the current fact count means some facts are findable by wording but not by meaning — worth mentioning if the user asks why something was not recalled. `extract.unextracted_events` is how many transcript lines extract has not examined. `pending_facts` is I not yet integrated. A large unextracted count with a healthy fact count means capture is writing D that extract has not examined. `intelligence` is billed consolidation spend (calls, tokens, elapsed), broken down by stage and provider for the last 24 hours, all time, and the last few runs. Embeddings are not this number — they are a separate API. Token fields are omitted when the provider did not report them, not shown as zero. `token_budget` is remaining room under optional intelligence.token_budget caps (per billed provider, rolling hour / day / week / month). Unset means unlimited. Over the cap, consolidate skips extract, holds the watermark, and does not fall back to the heuristic.

Record a raw exchange — a user message, your response, a tool call, a tool result, an artifact — as the episodic record consolidation later extracts facts from. Logging both sides gives that extraction the context to know what a reply refers to. Where the client has hooks configured, every event is logged for you automatically and you do not need to call this at all. Call it when there are no hooks, or when an exchange matters enough to preserve verbatim — a decision, a correction, a specification — and you want it recorded whether or not hooks are running. Duplicates are reconciled at consolidation, so logging something twice is safe. To store a fact you already know, use capture_fact instead: this tool records what was said, not what it means.

Search the knowledge base. Call this BEFORE answering questions that might benefit from what this store knows. If you have not called get_session_context (or loaded memory://briefing) this conversation, do that first — otherwise you start without this store's context. Returns facts ranked by relevance with source attribution and confidence scores. Three fields come back. `results` is integrated knowledge: deduplicated, reconciled against everything else known, entities resolved. Each result carries speaker_role when the primary event is known (user, assistant, system, or tool) and speaker when the transcript named the person — who uttered it, not who it is about. `pending` is what was captured recently and not yet consolidated — real, and usually the most recent thing you were told, but not yet checked against existing knowledge, so it may duplicate or contradict a fact in results. Trust results first; use pending to avoid forgetting something you were told minutes ago. `episodes` is filled only when results are empty: a short raw-log window around a keyword hit in the copied transcript, not yet extracted. It is not knowledge of the same standing — do not report it as an integrated fact. When semantic search is enabled, `results` also matches on meaning, so a query can surface a fact that shares none of its words. `pending` and `episodes` never do — they are keyword-only. A just-captured fact is findable by its own words but not yet by a paraphrase of them.