MCP Tools

The Graphnosis sidecar exposes 34 tools via the Model Context Protocol, organised into nine functional categories. Every connected MCP client — Claude Desktop, Claude Code, Cursor, and anything else that speaks MCP — sees the same 34. What a tool can actually reach is still governed by each engram’s sensitivity tier and the consent gate — by default a one-click in-app prompt for sensitive-tier recalls, silent for personal and public.

You can browse the full toolset inside the app too: open the MCP Tools button in the left sidebar (next to Settings). Each tool name opens a short explainer with example prompts you can paste straight into your AI client.

At a glance — the 34 tools

Category	Tools
Core memory (7)	recall · remind · remember · forget · apply · stats · vitality
Engram discovery (5)	list_engrams · suggest_engram · browse_engram · recent · get_engram_schema
Structured recall (4)	recall_structured · recall_with_citations · compare_engrams · cross_search
Source operations (3)	find_source · recall_source · transfer_source
Engram operations (2)	ingest_batch · engram_summary
Brain maintenance (3)	duplicate_pairs · healing_journal · gnn_status
Approximate (2)	audit_memory · check_duplicate
Conditional (1)	correct
Non-deterministic (7)	develop · predict · insights · gnn_neighbors · llm_query · llm_distill · confirm_data_access

How results are returned

Every tool returns a standard MCP text content block. The text is one of two things, noted per tool below:

• Plain text — a ready-to-read string (recall, remind, remember, apply, forget, develop, predict, llm_query, confirm_data_access).
• A JSON string — structured data the client can parse (everything else).

There is no separate “return object” — the JSON examples below show what that text string contains once parsed.

Determinism

Graphnosis sorts its tools into four determinism tiers. Each tool states its own tier in the description an AI client sees, so the client knows exactly what it is invoking:

Tier	What it means	Tools
Deterministic	Identical input always produces an identical result — no LLM, no randomness, fully auditable.	All Core memory, Engram discovery, Structured recall, Source operations, Engram operations, Brain maintenance tools; plus confirm_data_access.
Approximate	Vector-similarity scan — given the same embedding state, results are reproducible. No LLM involved.	audit_memory, check_duplicate
Conditional	Deterministic by default — correct supersedes the single closest-matching memory. Enabling the optional Neural Network (which widens the candidate set) or the optional Local LLM (which authors a multi-edit diff) makes it non-deterministic. The result’s mode field reports which path ran.	correct
Non-deterministic	Needs the optional Local LLM (or Neural Network). Retrieval is exact and auditable; the synthesised output varies between runs. Degrades to raw context when the LLM is off.	develop, predict, insights, gnn_neighbors, llm_query, llm_distill

One nuance for the deterministic tier: if the user has enabled the optional Graphnosis Neural Network, recall and remind may append a separate, clearly-labelled “Neural-network predictions” block. That appendix is the only non-deterministic part, and it is never mixed into the deterministic results.

---

recall

Determinism: deterministic. An identical query always returns identical memories — no LLM, no randomness, fully auditable.

Primary memory retrieval. Searches the user’s encrypted knowledge graph and returns a ready-to-use context block of the most relevant memories.

Parameters

Parameter	Type	Required	Description
query	string	Yes	Natural-language query or topic. Pass it in the user’s language — the search is multilingual (BGE embeddings + multilingual entity extraction).
maxTokens	integer	No	Token budget for the attached context. Default 2000. Range 100–8000.
maxNodes	integer	No	Maximum number of memory nodes to attach. Default 20. Range 1–50.

Return

Plain text — a Markdown context block of the recalled memories grouped by engram, followed by an audit footer summarising what was served per engram:

# Graphnosis context
The following memories from the user's personal graphs may be relevant.

## Graph: work
- The deployment pipeline runs on GitHub Actions, triggered on push to main.

---
Attached 1 memory node(s) / 24 tokens across 1 graph(s). Per-graph (tier · nodes · tokens): work · personal · 1n · 24t.

Notes

• The server enforces hard caps (50 nodes / 8000 tokens) regardless of what is requested.
• Sensitive engrams are governed by their per-engram “share with AI” setting. When an engram is sensitive and shared, recall still includes it but applies a tighter cap (5 nodes / 500 tokens). When it is not shared, it is excluded entirely.
• Every recall is auditable: the footer above, plus a structured audit line on the sidecar’s stderr that the desktop inspector tails.
• If the user has enabled the Graphnosis Neural Network, a separate “Neural-network predictions” block may be appended — clearly labelled and never mixed into the deterministic results.

Example

{
  "tool": "recall",
  "arguments": {
    "query": "database migration strategy",
    "maxNodes": 5,
    "maxTokens": 1500
  }
}

Examples in practice

• Everyday — Last month you told your AI which paint colour you picked for the spare room. Today you ask “what was that paint colour again?” — it calls recall, finds the note, and gives you the exact name without you digging through old chats.
• Technical — Mid-refactor you ask “why did we drop the Redis cache layer?” — recall surfaces the decision note from a past session, so the AI reasons from the actual rationale instead of guessing.

---

remind

Determinism: deterministic. An alias for recall, framed around the “remind me about X” intent — the same multilingual search, the same hard caps, the same plain-text context block. Use it when the user explicitly asks to be reminded of something (in any language: “remind me about…”, “amintește-mi de…”, “recuérdame…”).

Parameters

Identical to recall: query (required), maxTokens (optional, default 2000), maxNodes (optional, default 20).

recall and remind call the same underlying search and return the same shape — choosing one over the other is just a soft signal of intent to the user.

Examples in practice

• Everyday — You say “remind me what gift ideas I had for Mum’s birthday” — the phrasing signals intent, so the AI calls remind, which runs the same search as recall and pulls back the list you jotted down weeks ago.
• Technical — Before a release you ask “remind me of the open caveats on the auth migration” — remind returns the caveats you logged during the migration work, so nothing slips through the checklist.

---

remember

Determinism: deterministic. Saving the same note produces the same memory — no LLM, no randomness, and every write is auditable.

Store a new memory directly from a conversation so it persists across sessions.

Parameters

Parameter	Type	Required	Description
text	string	Yes	The content to store.
target_engram	string	No	Preferred. A human-friendly engram name (e.g. "Book Notes"). Resolved against existing engrams via exact-then-fuzzy matching; non-matches trigger a user-confirmation banner in the app (see below).
graphId	string	No	An exact engram slug (e.g. book-notes). Skips name resolution. An unknown slug routes through the same banner flow as target_engram rather than dead-ending.
label	string	No	Short label shown alongside the source in the Sources list. Defaults to a sensible placeholder.
kind	string	No	"clip" (default) — a discrete fact, note, or extracted text. "ai-conversation" — a turn or summary of the current AI ↔ user conversation. The Sources list shows these distinctly.

Return

Plain text confirming the write:

Saved to book-notes as clip:3c6e206d6aa7744913361348.

If the new note contradicts existing memory, a warning is appended naming the contradictions, so the AI can offer correct or forget as a follow-up.

Notes

• Text is chunked, embedded, and encrypted before storage — the same pipeline as file ingest.
• AI clients should prefer target_engram over graphId. It is name-tolerant (“Book Notes” / “book-notes” / “booknotes” all resolve to the same engram), and when the name does not exactly exist Graphnosis surfaces a user-confirmation banner instead of silently writing to the default engram.
• Without target_engram or graphId, the note goes to the user’s default engram — a fallback, not a recommendation.

The target_engram resolution flow

When target_engram (or an unknown graphId) is set, the sidecar runs a three-way resolver:

Resolver result	What happens
Exact match (normalized graphId or displayName)	Writes immediately.
Close matches (≥1 candidate above similarity threshold)	The tool returns an actionable error to the AI listing the closest matches by name. The app shows a banner top-center with ranked candidates (each labelled with the match reason — contains your text, same words, close spelling) plus a “Create new” option. The user picks one or creates a new engram.
No match	The tool returns an error listing all existing engrams. The banner offers “Create new” only.

The AI never auto-creates an engram or silently disambiguates — every new engram is a human-confirmed decision. The error returned to the AI is structured so a well-instructed client can relay the situation to the user without retrying the call.

Example

{
  "tool": "remember",
  "arguments": {
    "text": "Decided to use PostgreSQL for the new service. SQLite was ruled out due to concurrent write requirements.",
    "target_engram": "Work decisions",
    "label": "DB choice",
    "kind": "clip"
  }
}

Examples in practice

• Everyday — You tell your AI “save this — our plumber is Dan, 0712 345 678, and he wants 24 hours’ notice” — it calls remember with a target_engram like “Home contacts”, so the detail is there next time the sink leaks.
• Technical — After a long debugging session you say “note that the flaky CI test is a timezone bug, not a race condition” — remember stores it in your engineering engram, and the finding survives past the current session instead of being lost.

---

correct

Determinism: conditional. Deterministic by default; non-deterministic when the optional Neural Network or Local LLM is enabled.

Propose a natural-language correction to the user’s memory. Does not write anything — it returns a diff for review. Nothing is committed until the user approves the diff in the Graphnosis App (or, rarely, an AI client calls apply on the user’s explicit instruction).

The three paths

• Deterministic (mode: deterministic — no Neural Network, no Local LLM). Graphnosis recalls the single closest-matching memory and proposes one supersede edit — replacing it with the correction text while preserving the original for audit lineage. When nothing matches, the correction is proposed as a new memory instead. Identical input always yields an identical diff.
• GNN-expanded (mode: gnn-expanded — Neural Network enabled, no Local LLM). The candidate set is widened with GNN-predicted related memories; a strongly-predicted one can outrank the top recall hit and become the memory that is superseded. Still a single supersede, but the choice is GNN-influenced — and therefore non-deterministic.
• LLM-assisted (mode: llm-assisted — Local LLM enabled). The local LLM parses the correction against every candidate memory (including any GNN-surfaced ones) and may propose a multi-part diff (any mix of supersede / edit / delete / add). Most capable, but the proposed diff can vary between runs.

The path is chosen by what the user has enabled for the active cortex — the AI client does not pick. The result’s mode field reports which one ran.

Parameters

Parameter	Type	Required	Description
correction	string	Yes	A natural-language description of what is wrong and what it should be. Pass it in the user’s language.
graphId	string	No	Restrict the correction to a specific engram. When omitted, the engram is inferred from the closest-matching memory.

Return

A JSON string. mode is "deterministic", "gnn-expanded", or "llm-assisted"; preview is the proposed diff; candidates are the memories considered — recall hits plus, when the Neural Network is on, GNN-surfaced ones (each flagged with viaGnn):

{
  "diffId": "diff_m8x2k1",
  "mode": "deterministic",
  "preview": {
    "reasoning": "Deterministic correction (no Local LLM): superseding the closest-matching memory…",
    "edits": [
      {
        "kind": "supersede",
        "nodeId": "yBVlkQ-7DyfTucEFq2MQ0",
        "content": "Actually, we went to Greece in September 2020, not August.",
        "reason": "User correction (deterministic supersede)."
      }
    ],
    "adds": []
  },
  "candidates": [
    { "graphId": "personal", "nodeId": "yBVlkQ-7DyfTucEFq2MQ0", "text": "We went to Greece in August 2020…", "viaGnn": false }
  ]
}

Notes

• supersede is preferred over edit: it keeps the original memory for audit lineage, consistent with Graphnosis’ indelibility guarantee — a correction never destroys the prior memory, it demotes it.
• The diff stays pending in memory until the user approves or rejects it in the app. Always present the diff to the user before calling apply.
• Never call remember to “fix” something — that creates a duplicate, conflicting node the user has to clean up.

Example

{
  "tool": "correct",
  "arguments": {
    "correction": "The API endpoint changed from /v1/search to /v2/query in March 2025.",
    "graphId": "work"
  }
}

Examples in practice

• Everyday — Your AI mentions your anniversary is in June, but it’s actually July. You say “that’s wrong, our anniversary is in July” — correct proposes a diff superseding the old memory, and you review it in the app before anything changes.
• Technical — You realise a stored note says the service runs on Node 18 when you’ve since moved to Node 22. You tell the AI to fix it — correct returns a reviewed supersede diff; the original is kept for audit lineage and nothing is written until you approve.

---

apply

Determinism: deterministic. Writes an already-reviewed diff to the graph via the op-log; applying the same diff twice is idempotent.

Commit a correction diff that was proposed by correct.

Parameters

Parameter	Type	Required	Description
graphId	string	Yes	The engram the diff targets.
diffId	string	Yes	The diffId returned by correct.

Return

Plain text:

Applied.

Notes

• AI clients should almost never call this. It is normally invoked by the Graphnosis App after the user clicks Approve. Only call it when the user has explicitly reviewed a specific diff and asked you to commit it.
• Each operation in the diff is written as an op-log event, so the change is fully auditable and reversible.
• Fails if the diffId is unknown — there is no “apply the last one” shortcut by design.

Example

{
  "tool": "apply",
  "arguments": {
    "graphId": "work",
    "diffId": "diff_m8x2k1"
  }
}

Examples in practice

• Everyday — You usually just click Approve on the correction banner in the app, which commits the diff for you — the AI never touches apply. The one exception is when you explicitly say “yes, go ahead and apply that correction”, and only then does the client call it.
• Technical — You’re working in a terminal-only setup without the app window in front of you. After reviewing a specific diff’s diffId, you instruct the AI to commit it — apply writes the reviewed diff to the op-log as an auditable, reversible change.

---

forget

Determinism: deterministic. Soft-deleting the same node always yields the same result — no LLM, no randomness, and the delete is recoverable from the op-log.

Surgically soft-delete one or more specific memory nodes from an engram. Only the listed nodes are removed — the rest of the source they came from is completely untouched.

Node-level only — sources are user-only

forget operates at the node level, not the source level. Removing an entire ingested file, URL, or clip is a user-only action done from the Sources page in the Graphnosis app. An AI client has no API to delete a whole source — by design.

This matters: if a source has 500 nodes and the user only wants one stale fact gone, forget removes just that node. The other 499 are untouched.

Parameters

Parameter	Type	Required	Description
graphId	string	Yes	The engram slug (e.g. personal, rss-ai, work). Use list_engrams or stats to see valid slugs.
nodeIds	string or string[]	Yes	One nodeId or an array of up to 20 nodeIds. Node IDs come from recall_structured results — never guess or construct them.

How to get nodeIds — always use recall_structured first

1. Call recall_structured(query="<what the user described>", graphId="<engram>")
2. Show the user the matching node(s) — confirm which ones to remove.
3. Call forget(graphId="<engram>", nodeIds=["<id1>", "<id2>", ...])

Never skip the recall_structured step. Never pass a sourceId — that field does not exist on this tool.

Return

Plain text confirming how many nodes were soft-deleted:

Forgot 1 node: node_abc123.
Forgot 3 nodes: node_abc123, node_def456, node_ghi789.

Notes

• This is a soft delete — the user can recover deleted nodes via the app’s Recover flow. Nothing is permanently destroyed.
• forget removes only the nodes you name. The source record and every other node from that source remain intact.
• Always confirm with the user which node(s) to remove before calling.
• To fix content rather than delete it, use correct instead.

Example

{
  "tool": "forget",
  "arguments": {
    "graphId": "work",
    "nodeIds": ["node_abc123"]
  }
}

Examples in practice

• Everyday — You saved a to-do that’s no longer relevant. You tell your AI “remove that note about the UX polish cleanup” — the AI calls recall_structured to find the exact node, shows you the text to confirm, then calls forget with just that nodeId. Your other notes from the same session are untouched.
• Surgical cleanup — An ingested document has one outdated fact that keeps surfacing in recall. Rather than re-ingesting the whole document, the AI finds the specific node with recall_structured and removes it with forget. The rest of the document’s 40+ nodes stay in place.

---

stats

Determinism: deterministic. A direct read of ground-truth graph state — identical calls return identical data, no LLM, no randomness.

Inspect the ground-truth state of every engram in the active cortex — node counts and source counts per engram. Useful when the user asks “show me my graph” or to debug why recall returned nothing.

Parameters

Parameter	Type	Required	Description
includeNodes	boolean	No	If true, include up to 20 node-content previews per engram. Default false.

Return

A JSON string:

{
  "graphs": [
    {
      "graphId": "work",
      "totalNodes": 1840,
      "activeNodes": 1823,
      "softDeletedNodes": 17,
      "sources": 48
    }
  ]
}

With includeNodes: true, each engram object also carries a nodes array of up to 20 previews.

Example

{
  "tool": "stats",
  "arguments": { "includeNodes": true }
}

Examples in practice

• Everyday — You ask “how much have I actually saved into my memory so far?” — stats reads the ground-truth graph state and reports node and source counts per engram, so you see exactly what’s stored.
• Technical — A recall came back empty and you can’t tell why. You ask the AI to check the graph — stats with includeNodes shows which engrams hold which sources, revealing the notes landed in a different engram than expected.

---

develop

Determinism: mixed. Recall is deterministic and auditable; a local LLM then synthesises the plan, so the wording varies between runs. With no local LLM running it degrades to a deterministic raw-context dump.

Strategic planning grounded in the user’s own knowledge graph. Graphnosis recalls the relevant memory, then synthesises a plan — Situation → Approach → Key Actions → Risks & Gaps → Next Step. All computation is local.

Parameters

Parameter	Type	Required	Description
context	string	Yes	The domain or situation to plan for (e.g. “my book project”).
strategy	string	Yes	The approach to use (e.g. “lean MVP”, “bottom-up growth”).
goals	string	Yes	What success looks like (e.g. “publish a draft in 3 months”).
graphIds	string[]	No	Restrict recall to specific engrams. Defaults to all accessible engrams.
saveAsGoal	boolean	No	If true, the plan is also saved as a goal node for periodic check-ins.

Return

Plain text — a Markdown strategic plan, followed by a line naming how many memory nodes it referenced and across which engrams.

When the Local LLM is not enabled, develop instead returns the raw recalled memory, prefixed with a clear note that the model is off — so the AI can work from the context directly and tell the user how to enable a synthesized plan.

Examples in practice

• Everyday — You say “help me plan the garden makeover this spring, on a tight budget, finished by May” — develop recalls your past notes on the yard and synthesises a Situation → Approach → Key Actions → Risks & Gaps → Next Step plan grounded in what you’ve already recorded.
• Technical — You ask the AI to plan migrating a monolith to services using a strangler-fig approach, aiming to ship the first extracted service in a quarter — develop grounds the plan in your logged architecture decisions rather than generic advice.

---

predict

Determinism: mixed. Recall is deterministic and auditable; a local LLM then synthesises the risk/opportunity assessment, so the wording varies between runs. With no local LLM running it degrades to the raw recalled context.

Proactive risk and opportunity assessment before the user takes an action. Graphnosis recalls memory related to the action and uses the local LLM to surface past failures, constraints, blockers, and overlooked opportunities. All computation is local.

Parameters

Parameter	Type	Required	Description
action	string	Yes	The action or decision the user is about to take.
graphIds	string[]	No	Restrict recall to specific engrams. Defaults to all accessible engrams.

Return

Plain text — a Markdown assessment with Risks, Opportunities, and a Recommendation, followed by a line naming how many memory nodes it was grounded in.

When the Local LLM is not enabled, predict instead returns the raw recalled memory, prefixed with a clear note that the model is off — so the AI can assess it directly and tell the user how to enable a structured prediction.

Examples in practice

• Everyday — Before booking a contractor you ask “anything I should watch out for here?” — predict recalls your past notes on home projects and surfaces Risks, Opportunities, and a Recommendation, like a reminder that the last contractor ran weeks over schedule.
• Technical — About to enable a feature flag for all users, you ask the AI to assess it first — predict pulls memory tied to that rollout and flags past failures and constraints, such as a load issue that bit you the last time you skipped a staged rollout.

---

insights

Determinism: non-deterministic. Insights are produced by a background local-LLM loop; this tool only retrieves what was already computed — it does not trigger a new scan.

Returns the current pending insights — non-obvious patterns, gaps, opportunities, and conflicts the background analysis surfaced across all engrams. The loop runs roughly every six hours while a local LLM is available.

Parameters

Parameter	Type	Required	Description
dismissed	boolean	No	If true, include already-dismissed insights. Default false (active only).

Return

A JSON string — an array of insight objects, each with kind (pattern / gap / opportunity / conflict), title, body, and relevant node ids.

When the Local LLM is not enabled, insights instead returns a plain-text message explaining that insights come from a background local-LLM loop and there is nothing to retrieve until the model is turned on. With the LLM on, the array is simply empty until the loop has had a chance to run.

Examples in practice

• Everyday — You ask “noticed anything interesting across my notes lately?” — insights returns what the background loop already worked out, such as a pattern that your best writing sessions all happen before noon.
• Technical — You ask the AI “any conflicts or gaps in my project memory?” — insights hands back the pre-computed findings, like two notes that disagree on the production database version, without kicking off a fresh scan.

---

vitality

Determinism: deterministic. The vitality score is a fixed formula over current graph state — identical state yields an identical score, with no LLM and no randomness.

Returns the vitality score — a 0–100 measure of how alive and well-connected the engrams are. The score blends four ratios: connectivity (40%), average confidence (25%), recent activity (20%), and coherence — fewer unresolved duplicate pairs (15%).

Parameters

None.

Return

A JSON string:

{
  "overall": 82,
  "byGraph": { "work": 88, "personal": 74 },
  "computedAt": 1716290000000
}

Examples in practice

• Everyday — You ask “how healthy is my memory overall?” — vitality returns a 0–100 score, and a 74 on your personal engram nudges you to tidy up loosely connected notes.
• Technical — Tracking memory quality over time, you ask the AI for the current vitality — vitality reports the per-engram breakdown, and a dip flags a build-up of unresolved duplicate pairs dragging down the coherence component.

---

Engram discovery

These five tools let an AI client navigate your cortex without needing to guess engram names. All deterministic — metadata reads only.

list_engrams

Lists every engram in your cortex — names, sensitivity tiers, source counts, archive state. Use before routing a remember if you don’t already know what exists.

• Returns: JSON array of engram objects.
• Try saying: “What engrams do I have?” · “Show me all my memory collections.”

suggest_engram

Recommends the best engram to save a note into, based on token similarity between the note text and existing engram names. A pre-check before remember so the AI can avoid the routing banner when there’s an obvious fit.

• Parameters: text (required) · top_k (optional, default 3, max 5).
• Returns: JSON-ranked short-list with match scores.
• Try saying: “Where should I save this note about marathon training?”

browse_engram

Lists every source ingested into a specific engram — file paths, clip refs, timestamps, IDs — newest first. The right lookup before transfer_source when you need the exact sourceId. To forget specific memory nodes, use recall_structured → forget instead.

• Parameters: engram (required, slug or display name; fuzzy-matched) · limit (optional, default 20).
• Try saying: “What’s inside my Reading List engram?”

recent

The most recently ingested sources across all engrams, or scoped to one. Answers “what did I just save?” and verifies an ingest succeeded.

• Parameters: engram (optional) · limit (optional, default 10, max 50).
• Try saying: “What did I just save?”

get_engram_schema

Returns the metadata for one engram — display name, sensitivity tier, template, creation date. Used to confirm a tier before routing sensitive notes.

• Parameters: engram (required, slug or display name).
• Try saying: “What sensitivity tier is my Personal engram on?”

---

Structured recall

Four variants on recall for when the AI needs more than the standard prose context block.

recall_structured

Like recall, but results come back as a JSON array of node objects (nodeId, graphId, tier, score, text, sourceId) for programmatic processing — sorting by score, computing statistics, choosing which sourceIds to forward to a follow-up tool.

• Parameters: query (required) · maxTokens (default 2000) · maxNodes per graph (default 20) · only_engrams / except_engrams (optional scope filters).
• Try saying: “Recall my Q4 roadmap notes as JSON so I can sort them by score.”

recall_with_citations

Like recall, but each memory carries an inline citation to the source it was derived from (e.g. [clip:abc123]) — for traceable provenance per fact.

• Parameters: same as recall_structured.
• Try saying: “Tell me about the API redesign and cite the source for each fact.”

compare_engrams

Runs the same query against two engrams and returns the results side-by-side under separate headings — useful for contrasting work vs. personal, 2025 vs. 2026 plans, etc.

• Parameters: query · engram_a · engram_b · maxNodes (default 10).
• Try saying: “Compare what I know about Python in Work vs. Personal.”

cross_search

Federated recall over a hand-picked subset of engrams (not all), with results grouped and labelled per engram. Use when the user names multiple collections in a query.

• Parameters: query · engrams (array, at least one) · maxNodes (default 20 total).
• Try saying: “Search my Book Notes and Work engrams for distributed systems.”

---

Source operations

The op-log primitives — find, fetch, and move whole sources between engrams. All deterministic, all recoverable.

find_source

Find sources by a keyword substring match against sourceId, ref (label/path/URL), or kind — across all engrams or scoped to one. Returns each match with its exact engram slug, sourceId, kind, and timestamp.

• Parameters: keyword (required) · engram (optional, narrows the search to one engram) · limit (default 10).
• Try saying: “Where did I save that PDF about Raft?”

Call this before transfer_source

Always call find_source before transfer_source. Use the returned graphId (engram slug) and sourceId verbatim — never construct or guess either value.

To forget specific memories, use recall_structured (not find_source) — it returns nodeId values, which is what forget accepts.

recall_source

Returns the FULL content of a single saved source — every chunk, in ingestion order, with no similarity cutoff. Use when recall keeps returning partial results for a structured document (a plan, a numbered list, a meeting note) and you need the complete text.

• Parameters: sourceId (required, exact — use find_source first if unsure) · engram (optional, speeds up large cortexes).
• Try saying: “Pull up the complete text of my Q4 planning doc.”

transfer_source

Moves a single source (and every memory derived from it) from one engram to another via the op-log. Recoverable per-source.

• Parameters: sourceId · from_engram · to_engram.
• Try saying: “Move that file from Inbox to Work.”

---

Engram operations

Merging engrams is a user-only action

Merging an entire engram into another is done from Settings → Engrams in the Graphnosis app — AI clients cannot trigger this operation. This keeps a broad, hard-to-reverse action under explicit user control.

ingest_batch

Saves multiple notes in a single call — up to 20 items per batch, each with its own target_engram. For bulk-importing a list of facts without one remember per item.

• Parameters: items (array, max 20).
• Returns: JSON per-item success/error summary.
• Try saying: “Save these 5 facts about the project in one go: …”

engram_summary

A readable snapshot of an engram — node count, source count, and a sample of node-content previews. For orienting yourself before querying a new engram.

• Parameters: engram (required).
• Try saying: “What’s in my Reading List engram?”

---

Brain maintenance

Read-only windows into the autonomous brain engine that runs in the background while the app is open.

duplicate_pairs

Near-duplicate node pairs the brain engine has already flagged for review — high-confidence matches from the background scan, not ad-hoc searches. Resolve with correct (merge) or forget(nodeIds=[nodeId]) (remove one side). Requires the brain engine to be running.

• Try saying: “What does my brain think is duplicated?”

healing_journal

Audit log of autonomous corrections the brain engine applied in the background — merges, confidence adjustments, edge repairs. “What has my brain fixed on its own?”

• Try saying: “Show me autonomous corrections from the last week.”

gnn_status

Reports whether the Graphnosis Neural Network is enabled, how many predicted edges it has computed, and when it last ran. Use before gnn_neighbors to confirm the GNN has data.

• Try saying: “Is the neural network running?”

confirm_data_access

System-driven, headless-fallback only. The primary consent flow in v0.10+ is the in-app one-click prompt that pops automatically in the Graphnosis app when a gated recall fires — the AI client never calls this tool in normal desktop use.

This tool exists for environments without a GUI (sidecar running over SSH, in a Docker container, in CI) where the user can’t see the modal. In those cases the consent gate returns the legacy "⚠️ GRAPHNOSIS CONSENT REQUIRED" message instructing the user to read the current phrase from Settings → AI → Consent Phrases in the app and have the AI invoke confirm_data_access({ phrase, tier }). Validates the phrase locally and stores a consent record for the (client, tier) pair. AI clients never invent or guess the phrase. See AI Access Controls for the full protocol.

• Parameters: phrase (the exact phrase the user typed) · tier (personal or sensitive).

---

Approximate

Vector-similarity scans across the cortex — deterministic given the embedding state, no LLM involved.

audit_memory

Detects near-duplicate content across engrams by sampling top nodes from each engram and cross-searching them in all others above a similarity threshold. Approximate — samples rather than exhaustively comparing every pair. Useful before a merge or for periodic memory hygiene.

• Try saying: “Do I have duplicate notes anywhere?”

check_duplicate

Before remember, checks whether very similar content already exists in one engram or all of them. Returns matches above the threshold so the user can choose remember (new fact) or correct (update existing). Helps prevent duplicate-node pollution.

• Parameters: text · engram (optional).
• Try saying: “Before I save this note about Postgres tuning, is there anything similar already?”

---

Non-deterministic — Local LLM tools

The remaining synthesis tools require the optional Local LLM (Ollama). All computation stays on device — nothing leaves the machine. Each degrades gracefully when the LLM is off (raw context dump with a note explaining how to enable synthesis).

gnn_neighbors

Returns nodes the Neural Network predicts are related to a query — structural connections that lexical/embedding recall didn’t surface. Each result includes the GNN edge-probability score.

• Parameters: query · top_k (default 10).
• Try saying: “What else might be related to my notes on graph databases?”

llm_query

Recalls relevant memory then uses the local LLM to synthesise a direct answer from that recalled context — entirely locally. Use when the user wants an AI-synthesised answer grounded in their own memory, not just raw recalled nodes.

• Parameters: query · maxNodes (optional).
• Try saying: “Use the local model to answer: what’s the current state of my migration plan?”

llm_distill

Pass arbitrary text to the local LLM and ask it to extract discrete, self-contained facts worth remembering. Returns a JSON array of {text, label} objects ready to pass to ingest_batch or remember.

• Parameters: text · target_engram (optional).
• Try saying: “Extract the key facts from this meeting transcript for saving: …”