NeuroStack

Search or list agent-written memories. Without a query, lists recent memories. With a query, searches by content using FTS5 + semantic similarity, newer memories first among equals and superseded ones last. Without a workspace, memories in the workspace where most of the query's notes sit rank higher. Args: query: Optional search query (FTS5 + semantic). None = list recent. entity_type: Filter by type — "observation", "decision", "convention", "learning", "context", or "bug". None = all. workspace: Optional vault subdirectory to scope results limit: Max resul…

Merge two memories. Source is folded into target; source is deleted. Use this after vault_remember reports near_duplicates. Keeps the longer content, unions tags, keeps the more specific entity type, and tracks the merge in an audit trail. Args: target_id: Memory to keep (receives merged content) source_id: Memory to fold in (deleted after merge)

Return prediction errors — note or memory signals that surprised at retrieval. Note-centric (semantic distance between a note and the query that retrieved it): - low_overlap: cosine distance > 0.62 — note is semantically distant from what retrieved it - contextual_mismatch: note surfaced outside its expected domain context AND was only a weak fit (sim < 0.45) — a strong hit outside the context boost set is not a mismatch Only notes that surprised >= 2 distinct retrieval events are surfaced. Memory-centric (issue #38): - memory_drift: an agent-written memory has drifted from the current con…

Memories whose knowledge should be promoted into vault notes. Worklist, four buckets (issue #92): 'debt' (tagged promotion-debt), 'drift' (unresolved memory_drift rows), 'dead_handoffs' (stale context memories that read as handoffs; 'open-thread' tag exempts), 'uncovered' (durable memories the judgement model says no note records yet, each with its 0-3 'coverage' score and nearest note). Coverage verdicts are cached, so a memory is judged once until it or its nearest notes change; 'uncovered_pending' counts memories the judge did not answer this time. A downstream agent writes the notes and c…

Read a markdown file from the vault. By default returns the whole file. For a large note, pass `offset` and/or `limit` (both measured in characters of the decoded text) to read a bounded slice and page through it instead of pulling the whole body into context — the footprint fix behind lean reference mode (issue #62). When a bound is applied the result also carries `size_chars`, the `offset` used, and `truncated` (True when content remains past the returned slice). Args: path: Relative path under vault_root (e.g. "home/projects/foo.md"). Must end in .md. Absolute paths, '..', a…

Record that specific notes were retrieved and used in this session. Drives hotness scoring — frequently used notes score higher in future searches. This is the strong 'used' tier of the two-tier activation signal (issue #95); surfacing alone (search returns, auto-RAG vault_context injections) is logged server-side as weak 'primed' events. Mostly unnecessary now: the server infers a use from read-after-surface — opening a just-surfaced note via vault_read_file (issue #103). This call is the explicit override, for consumption the server cannot observe: acting on a snippet or a summary without …

Find semantically related notes using embedding similarity. Unlike vault_graph (which follows explicit wiki-links), this discovers connections based on semantic content similarity - notes that discuss similar topics even if not explicitly linked. Args: note: Note path (e.g. "research/predictive-coding.md") top_k: Number of related notes to return (default 10) workspace: Optional vault subdirectory prefix to restrict results (e.g. "work/acme-cloud")

Save a memory - persist an observation, decision, or learning for future retrieval. Memories are searchable alongside vault notes. Use this to record: - Architecture decisions made during a session - Bug root causes discovered - Conventions or patterns established - Context that should survive across sessions Args: content: The memory content to save (1-2 sentences recommended) tags: Optional tags for filtering (e.g. ["auth", "refactor"]) entity_type: Type of memory - "observation", "decision", "convention", "learning", "context", or "bug" source_agent: Name of the ag…

Search the vault. One query, results ranked best first. Pick `depth` by what you are going to do with the answer: - Answering a factual question ("what IP", "which model") -> "triples". - Deciding which note to open -> "summaries", or reference_only=True. - About to edit or act on a note's content -> "full". - Unsure -> leave "auto", which starts cheap and escalates. Transcript evidence says agents mostly leave "auto" and sometimes invent values like "shallow" or "quick". Only the four names above are accepted; anything else raises rather than silently falling back, because a silent fallbac…

End a memory session, storing the summary you write for it. Call at the end of a work session. NeuroStack does not write the summary: pass your own 2-3 sentence account of the session in ``summary``, or omit it to close the session with no summary. If auto_harvest=True, extracts insights from the most recent session transcript and saves them as memories. Args: session_id: The session ID returned by vault_session_start summary: Caller-written session summary; omit for none auto_harvest: Run harvest on the latest session (default True)

Start a new memory session to group related memories. Call at the beginning of a work session. All memories saved with the returned session_id will be grouped together and can be reviewed or summarized as a unit. Args: source_agent: Name of the agent starting the session (e.g. "claude-code", "cursor") workspace: Optional vault subdirectory scope (e.g. "work/acme-cloud")

Get index health: note count, embedding coverage, graph stats, triple stats.

Get pre-computed summary for a note by path or search query. Returns 2-3 sentence summary + frontmatter (~100-200 tokens) instead of reading the full file (~500-2000 tokens). Args: path_or_query: Note path (e.g. "research/predictive-coding.md") or search query

Report whether a fired trigger memory was followed (issue #136). Call once per fired memory, a few tool calls after vault_triggers returned it. Either outcome marks the logged firing (trigger_log.followed), so the obey count is measurable too (issue #159). followed=false also records a 'trigger_ignored' prediction error; the promotion queue's drift bucket lists the memory with its running ignore count and suggests retiring the trigger after three. Nothing is deleted automatically. Args: memory_id: The memory vault_triggers returned followed: True if the agent changed course because o…

Memories whose trigger tag matches the current moment (issue #131). A trigger is a tag with one of three prefixes: 'when-editing:<glob>' (file path of an Edit/Write), 'when-calling:<tool>' (tool name), 'when-error:<substring>' (tool error text). Harness hooks call this on tool events and inject the hits; the caller owns once-per-session suppression. Each hit is logged to trigger_log (issue #136) so the hook can later report with vault_trigger_outcome whether it was followed. Untagged memories are never returned. Args: event: One of "editing", "calling", "error" value: The path, tool …

Search knowledge graph triples for structured facts. Returns compact Subject-Predicate-Object facts (~10-20 tokens each). Use this for quick factual lookups instead of reading full notes. Args: query: Natural language search query top_k: Number of triples to return (default 10) mode: Search mode - "hybrid" (default), "semantic", or "keyword" workspace: Optional vault subdirectory prefix to restrict results (e.g. "work/acme-cloud")

Update an existing memory. Only provided fields are changed. Args: memory_id: The memory to update content: New content (re-embeds if changed) tags: Replace tags entirely (pass [] to clear) add_tags: Add these tags to existing set remove_tags: Remove these tags from existing set entity_type: Change type workspace: Change workspace scope ttl_hours: Set or change TTL. Pass 0 to make permanent.

Create or overwrite a markdown file in the vault. Commits + pushes to origin/main. Requires a YAML frontmatter block with required fields date, tags, type; hard-rejects writes that lack any of them. On push conflict, attempts `git pull --rebase --autostash` and retries once; on second failure, rolls back the local commit and returns pushed=false. Args: path: Relative .md path under vault_root. content: Full file content. Must start with `---\n...\n---\n` YAML. commit_message: Optional. Default: "vault_write_file: <path> (via MCP)".