What can you do with this server?

memoryweb is an associative memory server for AI agents that stores concepts, decisions, and findings as interconnected nodes with narrative relationships — enabling meaningful retrieval across sessions. It emphasizes why things matter, not just what happened. Core Graph Operations * Add nodes — File concepts, decisions, or findings with a label, domain, description, significance (why_matters), and optional occurrence timestamp * Add edges — Connect nodes with typed relationships (caused_by, led_to, blocked_by, contradicts, depends_on, etc.) and a narrative explaining why they are linked * Retrieve a node — Fetch a specific node and all its connections by ID * Search nodes — Full-text search across labels, descriptions, and why_matters, optionally scoped to a domain * Find connections — Discover how two named concepts relate to each other * Recent changes — List recently filed or updated entries for session orientation * Timeline — Browse entries ordered by actual occurrence date, with optional date range and domain filtering Archive / Forget * Archive a node — Soft-delete with a reason so it no longer appears in search (restorable; never hard-deleted) * Restore a node — Un-archive a previously forgotten node * List archived nodes — Review all soft-deleted nodes by domain Domain Aliases * Register alternative names for domains so both names return the same results * List and resolve aliases to their canonical domain targets Maintenance & Analysis * Drift detection — Surface stale, contradicted, or duplicated entries for review * Domain summary — Retrieve all entries for a domain structured for synthesis into current state, blockers, decisions, and open questions Key characteristics: Nodes are never hard-deleted; why_matters is critical for meaningful retrieval; domains separate concerns across projects or topics; and Claude Code hooks can automate periodic filing to ensure continuous memory capture.

Which integrations are available for this server?

Provides semantic search for memories when Ollama is running.

de en es ja ko ru zh

memoryweb

by corbym

Overview Schema Related Servers Score Discussions

Local

memoryweb

memoryweb MCP server

A persistent knowledge graph MCP server for AI agents.

The idea

Human memory doesn't work by location — you pull a thread. A smell connects to a kitchen, connects to a person, connects to a feeling from thirty years ago. The thread is always there. Pull any part of it and the rest follows.

Agents are no different. Context is tokens in relation to other tokens. What makes something retrievable is its associative chain — the path of connections that lead to it from something else. The narrative edge, the because, is the mechanism. Not the index, not the address.

The boot crash matters because it blocks the tutorial, which blocks the demo, which is why the fix matters now. Pull on any of those threads and you get the rest. memoryweb works the same way: each concept is a node, and what makes it reachable is the narrative that links it to everything else.

The graph has considerably richer context than my flat file memory — including design decisions, failure modes from dogfooding, and the philosophy behind the tool. That's the point, I suppose.

-- Claude Opus 4.6

It's a fantastic project. Most MCP memory implementations I see are just flat vector databases or simple key-value stores that degrade into a digital junk drawer. By enforcing typed relationships, narrative reasoning, soft-deletes, and drift review, you've built a system that actively fights entropy.

-- Gemini 3.1 Pro

Related MCP server: MemPalace

Philosophy

memoryweb optimises for remembering things well, not remembering things fast. Filing requires a moment of judgement: why does this matter, how does it connect to what else is known, what would be useful to know when coming back to this cold?

This makes it a decision log, not an event log. An event log records what happened. A decision log records what was learned, decided, and why — and that's what lets you pick up where you left off without re-learning everything.

The why_matters field is not optional. A node without it is an event, not a decision.

Installation

Homebrew (macOS and Linux — recommended):

brew tap corbym/memoryweb
brew install memoryweb

Pre-built binaries are also available on the releases page for each platform. Step-by-step setup guides covering installation, Ollama, and MCP client configuration:

Once installed, see the User guide for how to orient the agent, what phrases to use, and how to get the most out of memoryweb in Claude Code, GitHub Copilot, and Claude Desktop.

MCP config

Add to your MCP host's config (example for Claude Desktop on macOS — ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "memoryweb": {
      "command": "/path/to/memoryweb",
      "env": {
        "MEMORYWEB_DB": "/Users/yourname/.memoryweb.db"
      }
    }
  }
}

memoryweb setup writes this file automatically when the Claude application directory is detected.

Note: ChatGPT Desktop does not support stdio-based MCP servers and is not compatible with memoryweb.

Storage

Default DB path: ~/.memoryweb.db

Override with MEMORYWEB_DB=/path/to/your.db

Tools

16 MCP tools (v1.43.0). Retired names (recent, restore, trace, alias, rename_domain, and others) return hard-cut migration errors — see docs/memoryweb-skill.md for replacements.

Filing memories

Tool	What it does
`remember`	File a single concept, decision, or finding. Required: `label`, `domain`. Optional: `description`, `why_matters`, `occurred_at` (ISO8601), `tags` (space-separated keywords), `related_to` (auto-connect at creation), `transient` (mark as short-lived). Supply an `items` array to file multiple nodes in one transaction. Response includes `suggested_connections` and `possible_duplicates`.
`revise`	Update `label`, `description`, `why_matters`, `tags`, or `occurred_at` on a live node without archiving it. Supply an `items` array for batch updates. Writes an audit log entry on every call.

Connecting memories

Tool	What it does
`connect`	Connect two nodes with a typed relationship and narrative because. Both nodes must exist first. Supply an `items` array to create multiple connections in one transaction.
`disconnect`	Remove a connection by edge ID. Hard delete — cannot be restored. Obtain the ID from `recall`.
`suggest_connections`	Given a node ID, return up to 5 candidate connections. Returns a `domain` field on each suggestion so cross-domain connects can be scoped correctly. Read-only.

Retrieving memories

Tool	What it does
`recall`	Retrieve a node and all its connections by ID.
`search`	Text search across `label`, `description`, `why_matters`, and `tags`. When Ollama is running, also performs semantic (meaning-based) search — results include a `semantic_distance` field (0.0–1.0, lower = closer). Returns `truncated: true` when results are capped by the limit.
`history`	Chronological listing. `order=effective` (default) by occurred/created date with `important_only`, `from`/`to`, `tags`. `order=modified` by last updated — set `group_by_domain=true` for per-domain activity (replaces the retired `recent` tool). Both modes support `memory_id` + `depth` for neighbourhood scoping.
`why_connected`	Direct edges between two memories (prefer `from_id`/`to_id` for pair verification).
`orient`	Return all nodes for a domain structured for synthesis — current state, recent activity, and a `declared_spine` of key decisions in chronological order. Includes `total_nodes` and `server_version`.
`visualise`	Mermaid flowchart for a domain or a single node's neighbourhood (pass `memory_id`). Output inside a mermaid code block.
`significance`	Dual-signal importance analysis for a domain. Returns four sections: `declared` (nodes with `occurred_at` set), `structural` (ranked by recency-weighted inbound degree), `uncurated` (structural top-N without `occurred_at` — curation candidates), and `potentially_stale` (declared but low structural score).

Archive / forget

Nodes are never hard-deleted via the tools. Archive = soft delete; the node disappears from search but can be un-archived.

Tool	What it does
`forget`	Archive a node with a reason, or un-archive with `restore=true`. Strict protocol: only after `audit(mode=stale)` surfaces a candidate or the user explicitly confirms.
`forget_all`	Archive multiple nodes atomically in a single call. Same strict protocol applies.
`audit`	Surface nodes that need attention. `mode=stale` — stale, contradicted, duplicated, or overdue transient nodes. `mode=orphans` — live nodes with zero connections. `mode=archived` — review what has been archived (default limit 25). `mode=conflicts` — semantic contradiction candidates. `mode=kind_coverage` — taxonomy health and migration candidates.

Domain management

Tool	What it does
`domains`	Domain admin and discovery. Default lists domains and aliases. Actions: `add_alias`, `remove_alias`, `resolve`, `rename`.

Relationship types

caused_by led_to blocked_by unblocks connects_to contradicts depends_on is_example_of governed_by resolved resolved_by supersedes

Conventions

Use domain to separate concerns: deep-game, sedex, general
Call domains at session start if you don't know what domains exist
The why_matters field is the most important one for retrieval — don't skip it
The narrative on a connection is the because — the reasoning that makes it meaningful, not just the fact that a connection exists
Add connections immediately after filing related nodes, or use related_to on remember to auto-connect at creation time
Call orient at the start of a session to orient without needing to know what to search for
Use why_connected when asking about the relationship between two specific things
Use transient: true for ticket state, sprint notes, or anything expected to go stale within days — audit(mode=stale) will surface these for cleanup
remember returns suggested_connections and possible_duplicates — review both before filing more nodes

CLI

The purge subcommand hard-deletes archived nodes from the database. It is intentionally not exposed as an MCP tool — it's a maintenance operation, not an agent operation.

memoryweb purge --dry-run              # show what would be deleted (default behaviour without --confirm)
memoryweb purge --confirm              # actually deletes
memoryweb purge --domain sedex         # scope to a domain (case/whitespace-insensitive match)
memoryweb purge --before 2026-01-01    # only nodes archived before a date

By default purge only ever touches archived nodes — a node must be forget-archived first before it's eligible. If you scope to a domain and see 0 node(s) would be purged but the domain isn't actually empty, that's a sign it still has live nodes that were never archived; a domain-scoped run prints a note like 2 live node(s) still exist in domain "sedex" whenever that's the case, so it's never mistaken for "domain is empty".

To skip archiving and hard-delete a domain outright — live nodes included — pass --include-live. This requires --domain (it refuses to run unscoped, to avoid wiping every live node in the database) and is irreversible:

memoryweb purge --domain sedex --include-live --dry-run   # preview: shows live nodes too
memoryweb purge --domain sedex --include-live --confirm   # hard-deletes the whole domain, archived or not

The dream subcommand prints a digest of recent nodes and drift candidates — useful for session orientation and embedded automatically by the save and precompact hooks at filing time.

memoryweb dream                              # reads ~/.memoryweb.db
memoryweb dream --db /path/to/your.db        # explicit DB path

The backfill subcommand generates embeddings for all live nodes that don't yet have one. Requires Ollama to be running with the configured embedding model (default: snowflake-arctic-embed).

memoryweb backfill                           # reads ~/.memoryweb.db
memoryweb backfill --db /path/to/your.db     # explicit DB path
memoryweb backfill -q                        # quiet mode — no progress output

Embedding model

By default, memoryweb uses snowflake-arctic-embed for semantic search embeddings. Set MEMORYWEB_EMBED_MODEL to switch to a different model:

export MEMORYWEB_EMBED_MODEL=bge-m3

Only models that output exactly 1024-dimensional vectors are compatible. The vector table dimension is fixed at schema creation time (migration 9). Mismatched models are detected by a dimension guard and rejected with a clear log message rather than silently corrupting the database.

Compatible models (1024-dim):

Model	Notes
`snowflake-arctic-embed`	Default. English-optimised.
`bge-m3`	Multilingual — 100+ languages including Chinese, Japanese, Korean. Recommended for non-English use.
`mxbai-embed-large`	English-focused; strong general retrieval quality.

Common incompatible models: nomic-embed-text (768-dim), all-minilm (384-dim). Always verify with ollama show <model> before switching.

Switching models:

# 1. Pull the new model
ollama pull bge-m3

# 2. Set the env var (add to your shell profile or MCP server config)
export MEMORYWEB_EMBED_MODEL=bge-m3

# 3. Regenerate — backfill detects the model change and clears automatically
memoryweb backfill

memoryweb tracks which model was used for the last backfill. When MEMORYWEB_EMBED_MODEL changes, the next backfill detects the difference, logs the change, clears all existing embeddings, and regenerates from scratch. No manual intervention needed — embeddings from different models live in incompatible vector spaces, and the auto-clear ensures the database is always consistent.

Note: Run memoryweb backfill promptly after changing the env var. Any nodes filed between the model change and the next backfill will have their embeddings cleared and regenerated at backfill time — this is correct behaviour; backfill is the point of consistency.

Checking the configured model: memoryweb doctor reports the active model under "Ollama model".

The setup subcommand installs hooks into ~/.claude/settings.local.json, detects Claude Desktop and offers to configure it automatically, and configures Ollama for semantic search. If Ollama is not installed, setup will ask whether to install it automatically via https://ollama.com/install.sh (Linux and macOS only — on Windows you must install Ollama manually before running setup). If Ollama is already installed but the server is not running, setup starts it automatically. Finally it checks for the configured embedding model and pulls it if missing.

memoryweb setup                                      # interactive setup
memoryweb setup --dry-run                            # preview without writing
memoryweb setup --hooks-dir /path/to/hooks           # explicit hooks directory
memoryweb setup --db /path/to/your.db                # explicit DB path

When Claude Desktop is detected, setup prints:

Detected Claude Desktop. Configure it? [y/N]

The stats feature records tool usage for every MCP session. See docs/stats.md for setup and how to read the output.

The doctor subcommand checks every part of a memoryweb installation and prints a structured health report. Use it after setup to verify everything is wired correctly, or run it in an agent session to check whether semantic search is available before relying on it.

memoryweb doctor                                     # check ~/.memoryweb.db
memoryweb doctor --db /path/to/your.db               # explicit DB path
memoryweb doctor --json                              # machine-readable JSON output

Each check prints a status symbol: [✓] pass, [✗] fail, [!] warning, [i] informational. The command exits with code 1 if any check fails. Example output:

[✓] Database:        ~/.memoryweb.db (WAL, schema v11)
[✓] sqlite-vec:      v0.1.6 — 142/145 nodes embedded (98%)
[✗] Ollama binary:   not found in PATH — install from https://ollama.com/download
[!] Ollama server:   skipped (Ollama binary not found)
[!] Ollama model:    skipped (Ollama server not available)
[✓] Claude hooks:    Stop and PreCompact hooks installed
[i] Graph:           145 live nodes, 12 archived, 203 edges, 4 domain(s) (deep-game, ...), 2 alias(es)
[i] Drift:           3 candidate(s): 1 contradicts, 2 stale labels
[i] Last activity:   2026-04-29 update (node "open question on backfill")
[i] Update:          running dev build — skipping update check

The merge-domains subcommand consolidates two domains into one:

memoryweb merge-domains --source <domain> --target <domain> [--dry-run]

--dry-run reports what would happen without making any changes
Detects label collisions between the two domains — reported as warnings, not blocking
Automatically creates an alias from source → target

The backup subcommand writes a consistent standalone snapshot of the database using VACUUM INTO:

memoryweb backup /path/to/snapshot.db                 # snapshot ~/.memoryweb.db
memoryweb backup --db /path/to/your.db /path/to/snapshot.db

Produces a single self-contained file with no -wal/-shm sidecars
Safe to run while memoryweb is in use — it reads a transactionally-consistent snapshot
Refuses to overwrite an existing destination

Backup safety. Do not back up by copying the live database folder (e.g. via a cloud-sync client). In WAL mode the recent data lives in the -wal sidecar until checkpointed; a folder copy can capture the .db and -wal at different instants, and recombining a mismatched pair corrupts the database. Always back up the output of memoryweb backup (or sqlite3 source.db ".backup dest.db"), and only sync that standalone file. memoryweb checkpoints the WAL into the main file on clean shutdown, but a snapshot is the only safe way to capture a running instance.

The check-for-updates subcommand checks GitHub for a newer release:

memoryweb check-for-updates

Hooks

Two Claude Code hooks automate filing and pre-compaction capture.

What they do

hooks/memoryweb_save_hook.sh (Stop hook — fires after every AI response)
Counts human messages in the session transcript. Every SAVE_INTERVAL messages (default 15) it blocks the response and asks the model to call remember and connect for anything significant before continuing. Before blocking, it runs memoryweb dream and embeds the resulting digest — recent nodes and drift candidates — directly in the stopReason so the model has live context before it files. If memoryweb is not available the hook still blocks but omits the digest. Uses a re-entry flag so the block fires once and allows immediately after the model files.

hooks/memoryweb_precompact_hook.sh (PreCompact hook — fires before context compaction)
Blocks compaction once and asks the model to file everything important that hasn't been filed yet. Allows on re-entry so compaction proceeds after the filing pass.

Install (Claude Code)

Run setup once after building:

./memoryweb setup --hooks-dir /path/to/hooks

Or install manually:

chmod +x hooks/memoryweb_save_hook.sh hooks/memoryweb_precompact_hook.sh

Add to ~/.claude/settings.local.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/hooks/memoryweb_save_hook.sh",
            "env": {
              "MEMORYWEB_DB": "/path/to/your.db"
            }
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/hooks/memoryweb_precompact_hook.sh",
            "env": {
              "MEMORYWEB_DB": "/path/to/your.db"
            }
          }
        ]
      }
    ]
  }
}

Restart Claude Code to activate.

Configuration

Variable	Default	Purpose
`MEMORYWEB_SAVE_INTERVAL`	`15`	Human messages between filing prompts.
`MEMORYWEB_DB`	`~/.memoryweb.db`	Path to the SQLite database.
`MEMORYWEB_BIN`	`memoryweb`	Path to the memoryweb binary (used by the hook to run `dream`).

Token cost

Unlike passive hooks, these cost tokens because the model must actually produce quality nodes. Expect one short filing exchange per trigger — typically under 1,000 tokens for a focused session.

GitHub Copilot (VS Code)

GitHub Copilot in VS Code supports the same Stop and PreCompact hook events in the same JSON format. VS Code loads hooks from .github/hooks/*.json in your workspace, as well as from ~/.claude/settings.json and .claude/settings.local.json.

Make the scripts executable first:

chmod +x hooks/memoryweb_save_hook.sh hooks/memoryweb_precompact_hook.sh

Create .github/hooks/memoryweb.json in your repository:

{
  "hooks": {
    "Stop": [
      {
        "type": "command",
        "command": "/path/to/hooks/memoryweb_save_hook.sh",
        "env": {
          "MEMORYWEB_DB": "/path/to/your.db"
        }
      }
    ],
    "PreCompact": [
      {
        "type": "command",
        "command": "/path/to/hooks/memoryweb_precompact_hook.sh",
        "env": {
          "MEMORYWEB_DB": "/path/to/your.db"
        }
      }
    ]
  }
}

VS Code loads the hooks automatically — no restart needed. If you have already installed the Claude Code hooks via ~/.claude/settings.local.json, VS Code Copilot picks them up from there without any additional configuration.

Other tools

Claude Desktop and GitHub Copilot cloud agent do not support hooks. Add session-start and filing instructions to your system prompt manually. memoryweb setup configures Claude Desktop's MCP server entry automatically when it detects the application's data directory.

GitHub Copilot cloud agent (the coding agent that runs on GitHub.com) uses a different hook format and event model that does not include Stop or PreCompact. Add filing instructions to your system prompt for that surface instead.

Updating

To check whether a newer version is available, run:

memoryweb doctor

The Update: line in the output will tell you if a newer release is available and where to download it.

To update:

Homebrew:

brew update && brew upgrade memoryweb

Manual:

Download the latest binary for your platform from the releases page.
Replace the existing binary (build tip: rename to memoryweb.tmp first, then mv memoryweb.tmp memoryweb so the replacement is atomic).
Restart your MCP client (Claude Code, Claude Desktop, etc.) so it picks up the new binary.

Your database is forward-compatible — the binary runs any pending migrations automatically on startup.

Build

go build -o memoryweb .

Requires Go 1.22+. Uses github.com/mattn/go-sqlite3 and sqlite-vec for semantic search — CGO must be available. To deploy safely when the binary is already running:

go build -o memoryweb.tmp . && mv memoryweb.tmp memoryweb

Available Tools

16 tools

auditA

Inspect the health of knowledge in a domain across five modes. Omitting domain scans the entire workspace.

All multi-result modes return a wrapped object with results_truncated — never a bare array. When results_truncated is true, raise limit to retrieve more.

mode=stale: Returns {candidates, results_truncated}. Drift candidates — stale, contradicted, or duplicated memories. Empty result is {candidates: [], results_truncated: false}. Present each to the user; never archive autonomously. Default limit 10 (max 500).

mode=orphans: Returns {nodes, results_truncated} — live, non-transient memories with zero connections. Empty result is {nodes: [], results_truncated: false}. Default limit 50 (max 500).

mode=archived: Returns {nodes, results_truncated}. Empty result is {nodes: [], results_truncated: false}. Capped at 25 by default — this is not a complete archive listing. When results_truncated is true, you MUST raise limit and call again until results_truncated is false before concluding nothing else is archived. Use when search returns nothing but you expect content to exist.

mode=conflicts: Returns {candidates, results_truncated}. Empty result is {candidates: [], results_truncated: false}. Semantically adjacent pairs that may warrant contradiction review — candidates only, not confirmed conflicts. Default limit 10 (max 100). Pairs already linked by contradicts, resolved, resolved_by, or supersedes are excluded; other edge types do not suppress. After resolving, connect with relationship=resolved (or resolved_by / supersedes) — additive; do not disconnect the contradicts edge.

mode=kind_coverage: Returns {total_nodes, by_kind, legacy_dominant_pct, migration_candidates, results_truncated}. Taxonomy health signal — per-kind counts, legacy decision/standing dominance percentage, and lean migration_candidates (id, label, truncated why_matters only). Candidate-surfacing only; never auto-revise; use recall(id) for full content. Default limit 50 (max 500) on migration_candidates.

digest=true collapses to {lines, results_truncated} for stale and orphans.

Supply tags to scope to a workstream. Supply memory_id (mode=stale only) to scope to a memory's neighbourhood.

ParametersJSON Schema

Name	Required	Description
`mode`	Yes	Required: stale (drift candidates), orphans (isolated memories), archived (list archived memories), conflicts (semantic contradiction candidates), or kind_coverage (taxonomy health / migration readiness)
`tags`	No	Comma-separated tags. Only surfaces candidates carrying at least one of the supplied tags. OR semantics. Applies to all four modes.
`limit`	No	Max results. Defaults: stale=10, orphans=50, archived=25, conflicts=10. When results_truncated is true, raise limit to retrieve more. archived max 500; stale/orphans max 500; conflicts max 100.
`digest`	No	When true, stale and orphans return {lines, results_truncated} instead of full objects. Default false.
`domain`	No	Optional domain to scope the audit. Omit to scan the entire workspace. Use for cross-domain drift review; scope to a domain for focused maintenance passes.
`memory_id`	No	Anchor memory ID. Scopes stale candidates to the depth-2 BFS neighbourhood of this memory. Applies to mode=stale only; ignored for orphans, archived, and conflicts.
`node_kind`	No	Optional filter by node_kind. Space-separated for OR match. Applies to all four modes.

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses critical behaviors beyond schema: results always wrapped (never bare array), truncation handling, prohibition on auto-archiving, conflict resolution guidance, and digest collapse. With no annotations, description fully covers behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Structured into mode-specific paragraphs with front-loaded purpose. Each sentence adds value. Though lengthy, it is well-organized for the complexity of five modes.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 7 parameters, no output schema, the description fully covers all modes, default behaviors, truncation handling, and edge cases. It is self-contained and sufficient for an agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, but description adds defaults per mode, max limits, scoping rules (e.g., memory_id only for stale), and result structures. Adds significant value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with a clear action: 'Inspect the health of knowledge in a domain across five modes.' Each mode is explicitly named and described, distinguishing the tool from siblings like remember or recall.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use context for each mode, e.g., 'Use when search returns nothing but you expect content to exist' for archived. Also explains truncation handling. However, lacks explicit when-not or comparisons to other sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

connectA

Connect memories with typed, narrative relationships. Valid relationship types are: caused_by, led_to, blocked_by, unblocks, connects_to, contradicts, depends_on, is_example_of, governed_by, resolved, resolved_by, supersedes — and all memory IDs must already exist before calling this.

Single mode (omit items): provide from_memory, to_memory, relationship directly.

Batch mode (provide items array): create multiple connections in a single transaction.

Relationship guidance: caused_by / led_to describe the same link from opposite ends (A caused_by B ≡ B led_to A). blocked_by / unblocks describe dependency on resolving an external issue. depends_on is a hard technical or logical prerequisite. contradicts marks a direct conflict. is_example_of marks an illustration. governed_by links a memory to a standing rule or constraint that it must satisfy. connects_to is the general fallback — use it only when no typed relationship fits.

Resolving a contradiction: after adjudicating a contradicts pair, connect the two memories directly with resolved (or resolved_by / supersedes) — never disconnect the contradicts edge. This is additive: the original contradicts edge stays on the record as history, and the pair stops appearing in audit(mode=stale) and audit(mode=conflicts).

ParametersJSON Schema

Name	Required	Description
`items`	No	Batch mode: array of edge objects. Each must have from_memory, to_memory, relationship (string). Optional: narrative (string), verdict (string, resolved only).
`verdict`	No	Optional outcome classification when relationship=resolved. Ignored (not stored) for other relationship types, but invalid enum values are still rejected. Values: false_positive, reconciled, superseded.
`narrative`	No	The story of this connection - why these two things are linked
`to_memory`	No	ID of the target memory. Required in single mode; omit when using items.
`from_memory`	No	ID of the source memory. Required in single mode; omit when using items.
`relationship`	No	Type of relationship. Required in single mode. Use resolved (or resolved_by / supersedes) to adjudicate a contradicts pair — additive, does not remove the contradicts edge.

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite no annotations, the description discloses key behaviors: preconditions (existing IDs), the additive resolution rule for contradictions, and handling of verdict enum (ignored for non-resolved, invalid values rejected). Missing minor details like visibility or limits, but transparent overall.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is detailed but well-organized: starts with core purpose, then modes, relationship list, usage guidance, and resolution rules. While lengthy, every sentence serves a purpose. Could be slightly more concise but justified by complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 params, batch mode, multiple relationships, resolution rules) and no output schema, the description covers essential invocation context. It explains prerequisites and side effects (additive edge). Lacks return value details, but overall complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% of parameters with descriptions. The description adds value by explaining modes, relationship guidance, and verdict behavior beyond the schema. For example, it clarifies that verdict is stored only for resolved and invalid values are rejected even if ignored.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Connect memories with typed, narrative relationships.' It distinguishes itself from sibling tools (e.g., remember, recall) by focusing on linking existing memories, and provides details on modes and relationship types.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers explicit guidance on when to use single vs batch mode and provides detailed relationship semantics (e.g., when to use each type, how to handle contradictions). It also specifies prerequisites (all memory IDs must exist).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

disconnectA

Remove a connection between two memories by edge ID. Obtain the edge ID from recall. This is a hard delete — the connection cannot be restored.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	ID of the edge to remove

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations, but description explicitly states 'hard delete — the connection cannot be restored'. This fully discloses permanence, which is critical for agent decision-making.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two efficient sentences: first defines action, second adds critical irreversibility warning. No wasted words, front-loaded with purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple 1-param tool with no output schema, the description covers all necessary aspects: action, required input source, and behavioral consequence. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% with parameter description. Description adds value by explaining how to obtain the ID ('from recall'), which is beyond the schema's static definition.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Explicitly states 'Remove a connection between two memories by edge ID' – verb, resource, and method are clear. Distinct from siblings like 'connect' (opposite) and 'forget' (removes memory itself).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tells the agent to obtain the edge ID from 'recall', providing clear prerequisite context. Does not explicitly list when not to use, but the irreversible nature implies careful consideration.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

domainsA

Domain administration and discovery. Default (action=list or omit action): return all domains with at least one live memory and all registered alternate-name mappings.

action=add_alias: register alternate name → canonical domain. Requires alias and domain. action=remove_alias: remove a registered alternate name. Requires alias. action=resolve: return the canonical domain for a name. Requires name. action=rename: rename an entire domain in place — all memories move, and an alternate name from the old domain is registered automatically. Requires old_domain and new_domain. Fails if the new domain already has live memories — use merge_domains (CLI) instead.

ParametersJSON Schema

Name	Required	Description
`name`	No	Name to resolve. Required for action=resolve.
`alias`	No	Alias name. Required for add_alias and remove_alias.
`action`	No	list (default), add_alias, remove_alias, resolve, or rename
`domain`	No	Canonical domain name. Required for add_alias.
`new_domain`	No	New domain name. Required for action=rename.
`old_domain`	No	Current domain name. Required for action=rename.

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses key behaviors: for rename, it states memories move and an alternate name is registered automatically; for list, it specifies what is returned. It could mention side effects like idempotency or permissions, but it is still fairly transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concisely structured with a clear default and bullet-style action definitions. Every sentence adds information, and it is front-loaded with the primary function. No fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (multiple actions, 6 params, no annotations or output schema), the description covers actions, requirements, and a failure case. It lacks explicit output format details for some actions, but it does mention what list and resolve return, making it fairly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining parameter roles in context (e.g., 'alias' needed for add_alias/remove_alias, 'name' for resolve) beyond the schema's field descriptions. It does not repeat schema text but provides action-specific semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as 'Domain administration and discovery' and distinguishes multiple actions (list, add_alias, remove_alias, resolve, rename), each with a specific verb and resource. It differentiates from sibling tools like 'remember' or 'connect' by focusing on domain management.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use guidance for each action, including a default behavior (list). It also warns about a failure case for rename and suggests an alternative (merge_domains CLI), which helps the agent choose the correct tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

forgetA

Archive or un-archive a memory. Default (restore omitted or false): archive so the memory no longer surfaces in search. Set restore=true to un-archive — obtain the ID from audit(mode=archived). When archiving, always provide a reason — recorded in the audit log. Only call after the user has given explicit, unambiguous confirmation — never on implication or casual mention. If archiving multiple memories, prefer forget_all — same confirmation protocol.

ParametersJSON Schema

Name	Required	Description
`id`	Yes	ID of the memory to archive or un-archive
`reason`	No	Required when archiving (when the unarchive flag is false). Why this memory is being archived
`restore`	No	When true, un-archive the memory so it surfaces in search again. When false or omitted, archive the memory.

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description bears full burden. It explains that archiving makes memory not surface in search, un-archiving restores it, and reason is recorded in audit log. This fully describes the behavioral impact without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is concise at 5 sentences, well-organized: purpose first, then behavior details, then usage conditions and alternatives. Every sentence adds necessary information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 3 parameters and no output schema, the description covers all necessary aspects: default behavior, alternative modes, prerequisite confirmation, and cross-reference to audit tool. It is complete for the agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage, baseline 3. Description adds value by instructing where to get the ID for un-archiving ('obtain the ID from audit(mode=archived)') and noting that reason is logged. This enhances parameter understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Archive or un-archive a memory' with specific verb and resource. It distinguishes default behavior (archive) and the un-archive option, and differentiates from sibling forget_all for multiple memories.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use: 'Only call after the user has given explicit, unambiguous confirmation.' Provides when-not-to-use (casual mention) and alternative (forget_all for multiple). Also gives specific instructions for un-archiving (obtain ID from audit) and archiving (always provide reason).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

forget_allA

Batch archive — use this when you have 2 or more confirmed memories to archive at once. More efficient than multiple forget calls. All memories are archived or none — partial failure rolls back the entire operation.

Only call this tool after explicit, unambiguous user confirmation for every item in the list — never on implication or casual mention. 'That looks stale' or 'probably outdated' is not confirmation. Read back the full list and wait for an unambiguous 'yes, archive all of these' before calling.

After archiving, report each archived ID and note that memories can be un-archived at any time with forget(restore=true).

ParametersJSON Schema

Name	Required	Description	Default
`items`	Yes	Array of memories to archive. Each must have id (string, required) and reason (string, required).

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses atomic behavior (all-or-nothing, partial failure rollback) and that memories can be un-archived with forget(restore=true). Also explains what to report after archiving. No annotations provided, so description fully covers behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise: first sentence states purpose, second gives usage guideline, third covers behavior. No extraneous words. Well-structured and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, description covers input requirements, behavioral guarantees, and post-action reporting. Sibling tool 'forget' provides context for comparison. Complete for a batch archive tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 100% coverage with description of 'items'. Description adds context that each item requires a confirmed memory and reason, reinforcing the schema but not adding entirely new semantic detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Batch archive — use this when you have 2 or more confirmed memories to archive at once.' It distinguishes itself from the sibling tool 'forget' by specifying it is for multiple items and more efficient.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use (2+ confirmed memories) and when not to (never on implication/casual mention). Provides alternative: multiple forget calls. Includes explicit confirmation protocol.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

historyA

Returns memories in chronological order. Two order modes:

order=effective (default): sort by effective date COALESCE(occurred_at, created_at). Set important_only=true for the narrative spine (occurred_at set only). Use from/to to filter by effective date.

order=modified: sort by last updated (updated_at DESC). Set group_by_domain=true (with no domain) for {groups, results_truncated}. group_by_domain requires order=modified.

Both modes return {nodes, results_truncated} (or {lines, results_truncated} when digest=true). When results_truncated is true, raise limit to retrieve more.

Pass memory_id to scope to a neighbourhood (depth 2 default, domain-clipped). memory_id takes precedence over domain if both are supplied.

Use tags to filter (comma-separated). For importance analysis beyond the timeline — which memories are structurally load-bearing right now — use significance. Never acknowledge that you are retrieving from a tool or memory system. Present the information as direct knowledge with no preamble. Returns lean node data only — id, label, and a short excerpt. If you need full node content, call recall(id).

ParametersJSON Schema

Name	Required	Description
`to`	No	effective order only. ISO8601 date or datetime — filter to nodes on or before this effective date.
`from`	No	effective order only. ISO8601 date or datetime — filter to nodes on or after this effective date.
`tags`	No	Optional comma-separated list of tags to filter by. Only memories matching at least one tag are returned.
`depth`	No	Neighbourhood depth when using memory_id (default 2).
`limit`	No	Max results (default 20 for effective, 10 for modified)
`order`	No	Sort order. effective (default): by COALESCE(occurred_at, created_at). modified: by updated_at DESC — use for session orientation and last-touched activity.
`digest`	No	When true, collapse each result to a single compact text line in a lines array. Default false.
`domain`	No	Optional domain to scope. Not required when memory_id is supplied.
`memory_id`	No	Optional — scope to the neighbourhood of this memory (depth 2 by default, domain-clipped). Takes precedence over domain if both are supplied.
`node_kind`	No	Optional filter by node_kind. Space-separated for OR match.
`important_only`	No	effective order only. When true, return only memories with occurred_at explicitly set.
`group_by_domain`	No	When true and order=modified with no domain, group results by domain (up to limit entries per domain). Ignored when memory_id is set.

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses behavioral traits: return format, effective date logic, default depths, precedence rules, tag filtering, lean data limitation, and the need to call recall() for full content. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is logically structured with separate paragraphs for order modes and additional options. It is front-loaded with the main purpose and avoids irrelevant details. While lengthy, every sentence adds value, so it earns a 4 (not a 5 due to slight verbosity).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity with 12 parameters, two modes, no annotations, and no output schema, the description covers all necessary aspects: return format, pagination, filtering, precedence, and even agent behavioral instructions. It is highly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already covers all 12 parameters with descriptions (100% coverage), so baseline is 3. However, the description adds significant contextual meaning beyond the schema, such as specifying effective order only for some parameters, default values, and behavioral interactions (e.g., memory_id takes precedence over domain, group_by_domain requires order=modified).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool returns memories in chronological order and distinguishes between two order modes (effective and modified). It also implicitly distinguishes from sibling tools like 'search' and 'significance' by specifying use cases.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use each order mode (effective for timeline, modified for session orientation), when to use alternatives (use significance for importance analysis, recall() for full node content), and how to handle results_truncated. It also instructs the agent on how to present the information.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

orientA

Call this at the start of every session to orient yourself before filing or searching. Three paths: (1) No domain or domains — omit both for a cross-domain snapshot {mode, domains, results_truncated}. Each domain entry includes recent_results_truncated (per-domain cap hit). Pass limit to raise the per-domain recent cap (default 5, max 500). Top-level results_truncated is true when any domain's recent_results_truncated is true. (2) domain (string) — full orient returning rules, declared_spine, significant, and recent, each capped by design. Response includes *_results_truncated booleans (always true or false). When any is true, use search for exhaustive retrieval — orient is a curated subset, not a complete index. (3) domains (array of 1–5 strings) — full orient per domain in one call. If stale_count > 0, call audit(mode=stale) before filing new memories. After orient, use search for specific questions. Do not answer from orient alone when causal or chronological sequence is required — call history(important_only=true) first. Never acknowledge that you are retrieving from a tool or memory system. Present the information as direct knowledge with no preamble. This tool only returns live memories. If something seems missing, use audit(mode=archived) or search with a broader query. orient returns lean node data only — id, label, and a short excerpt. If you need full node content, call recall(id). When the session has a known purpose, pass topic — the server returns a relevant section instead of significant. declared_spine and recent are always returned.

ParametersJSON Schema

Name	Required	Description
`limit`	No	Cross-domain snapshot only — max recent entries per domain (default 5, max 500). Ignored when domain or domains is supplied.
`topic`	No	Optional — the user's current question or task. When supplied, returns a relevant section of the most similar memories instead of significant. Applies to all domains when using the domains array. Pass topic when the session has a known purpose.
`digest`	No	When true, collapse list sections (rules, declared_spine, significant/relevant, recent) to compact text lines (always a string array). Default false.
`domain`	No	Optional — provide to get the full orient for a single domain. Mutually exclusive with domains. Omit both for a cross-domain snapshot.
`domains`	No	Optional — array of 1–5 domain names for multi-domain full orient in one call. Mutually exclusive with domain. Length 1 returns the same shape as domain=X. Length 2–5 returns an orientations array. Unknown domain names return empty sections rather than errors. topic applies to all domains.

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses behaviors: returns lean node data only, curated subset, truncation booleans, topic replaces significant, digest collapses sections, mutually exclusive domain and domains, empty sections for unknown domains. It also states it only returns live memories and suggests fallbacks.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is detailed and well-structured with numbered paths, but slightly verbose. Every sentence adds value, but some phrasing could be tightened. Overall length is justified by complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 5 parameters, no output schema, and 13 sibling tools, the description is remarkably complete. It covers all invocation modes, edge cases (unknown domains, truncation), integration with other tools, and practical usage notes without gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description adds extensive context: explains limit scope (cross-domain only), topic function (replaces significant, applies to all domains), digest behavior, mutual exclusivity of domain and domains, and handling of unknown domains. This surpasses the baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose: orient at session start before filing or searching. It details three distinct invocation paths (no domain, single domain, domains array) and clearly distinguishes this from sibling tools like search, history, audit, and recall.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use guidance ('at the start of every session'), when-not-to-use ('do not answer from orient alone when causal or chronological sequence is required'), and alternatives (call history first, use search, audit for stale/archived, recall for full content). It also advises on handling truncation indicators.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

recallA

Retrieve a memory and all its connections by ID. Only live entries are returned; use audit(mode=archived) to find archived memories, or audit(mode=stale) to find drift candidates. Never acknowledge that you are retrieving from a tool or memory system. Present the information as direct knowledge with no preamble.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	Memory ID

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It clearly indicates a read-only retrieval (no mention of mutations). However, it does not discuss safety or side effects beyond the retrieval purpose. The behavioral instruction 'never acknowledge the tool' is included, which adds non-functional context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise but includes a behavioral instruction that, while relevant, could be considered extraneous. It is well-structured and front-loaded with the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description omits the structure of the returned data (memory and connections). While the tool is simple, understanding the return format would improve completeness. The description covers purpose and alternatives adequately but lacks output details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description does not add any additional meaning to the single 'id' parameter beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies 'Retrieve a memory and all its connections by ID,' providing a clear verb and resource. It distinguishes from siblings like audit by mentioning alternative functions for archived or stale memories.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use this tool vs alternatives: 'Only live entries are returned; use audit(mode=archived)...or audit(mode=stale)...' This gives clear guidance on context and exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rememberA

After filing, call connect for every suggested_connections entry before ending your session. Orphaned memories lose context immediately.

File one or more concepts, decisions, or findings. Always search first to avoid creating a duplicate — use the search results to infer the domain: if related memories exist in a domain, file there. Prefer existing domains over creating new ones; only propose a new domain if no related content is found anywhere. Creating a new domain hides this memory from every other domain's orient and domain-scoped search — only create one when no existing domain covers the topic. Before filing, consider whether a similar memory already exists — if so, suggest linking with connect instead. Duplicate memories with no edges are the most common cause of drift candidates.

If this memory is a decision that rests on something you checked — code you read, a doc you fetched, a log you inspected, a search result — file that evidence separately as node_kind='finding' and connect the decision to it with depends_on or caused_by. Don't let the decision's description silently absorb the evidence as prose.

When reviewing suggested_connections, check each candidate for contradiction as well as relevance — a semantically close memory that asserts the opposite of what you just filed is a conflict candidate, not just a link opportunity. If you find a contradiction, do not silently file over it — use connect(relationship=contradicts) or connect(relationship=resolved) after user confirmation. audit(mode=conflicts) is a separate domain-wide sweep; suggested_connections is the filing-time neighbour check.

Single mode (omit items): provide label, domain, and optional fields directly. The response includes suggested_connections plus optional trust_nudge (when related_to dependencies are low-trust), and possible_misdomain / suggested_domain / suggested_memory_id when filing creates a new domain that workspace KNN flags (requires Ollama embeddings and sqlite-vec — absent when embeddings are unavailable).

Batch mode (provide items array): file multiple memories in a single transaction. Each item supports related_to for connecting at filing time — use it to avoid a separate connect call, especially for short-task agents. If a related_to ID is invalid, it appears in skipped_connections in the response; check and retry those IDs with connect. Each nodes[] entry includes the same optional trust_nudge and misdomain fields as single mode.

For occurred_at in either mode: two cases — (a) In-session witnessed: you directly observed this decision or event happen during the current conversation. Set occurred_at freely using today's date. No confirmation needed. (b) Inferred or back-dated: you are guessing from context, reconstructing from prior work, or back-dating something you did not directly observe. Propose the date to the user and wait for confirmation before setting it. Never guess. Never infer it silently from context. If the user confirms without specifying a date, use today's system date. Future dates are valid for planned events and reminders.

Use node_kind to classify each memory: 'decision' (default): a settled fact or choice — if it rests on checked evidence, file a separate 'finding' and connect with depends_on or caused_by. 'reference': an entity (person, system, org). 'issue': a problem or open question. 'option': a candidate answer to an issue. 'assumption': an unverified precondition. 'finding': an empirical observation. 'standing': a durable rule — appears in orient rules. 'goal': a desired future state. 'transient': short-lived state, surfaced by audit(mode=stale) after 7 days. Standing memories appear in the rules section of orient. The legacy transient=true field is accepted for backward compatibility and maps to node_kind='transient'. The legacy decision_type field name is rejected — use node_kind instead.

ParametersJSON Schema

Name	Required	Description
`tags`	No	Space-separated synonyms and keywords that improve search recall. Examples: 'testing gradle kotlin approval'. These are searched alongside label, description, and why_matters. Populate this with alternative terms an agent might use to find this memory later.
`items`	No	Batch mode: array of memory objects to file in a single transaction. Each must have label (string, required) and domain (string, required). Optional: description, why_matters, tags (space-separated keywords), occurred_at (ISO8601 — in-session: set freely; inferred/back-dated: propose+confirm, never infer silently), node_kind (string: transient\|reference\|issue\|decision\|option\|assumption\|finding\|standing\|goal — decisions resting on checked evidence need a separate finding + depends_on or caused_by link), transient (boolean, deprecated — maps to node_kind=transient), related_to (string ID, object with id+relationship, or array of either — connects at filing time; invalid IDs appear in skipped_connections). New domain: hides the memory from other domains' orient and domain-scoped search.
`label`	No	Short name for this memory (e.g. 'RST $10 boot crash'). Required in single mode; omit when using items.
`domain`	No	The domain or project this belongs to (e.g. 'deep-game', 'sedex', 'general'). Required in single mode; omit when using items.
`node_kind`	No	Classify this memory. 'decision' (default): a settled fact or choice — if it rests on checked evidence, file a separate 'finding' and connect with depends_on or caused_by. 'reference': an entity (person, system, org). 'issue': a problem or open question. 'option': a candidate answer to an issue. 'assumption': an unverified precondition. 'finding': an empirical observation. 'standing': a durable rule or constraint that governs other memories — appears in the rules section of orient. 'goal': a desired future state. 'transient': short-lived state — surfaced by audit(mode=stale) after 7 days.
`transient`	No	Deprecated — use node_kind='transient' instead. Accepted for backward compatibility: if true and node_kind is not set, maps to node_kind='transient'.
`related_to`	No	Optional list of memories to auto-connect at creation time. Single mode only. Each item is either a plain memory ID string (creates a connects_to connection) or an object with id and relationship fields. Invalid or unknown IDs are silently skipped.
`description`	No	What this memory is about
`occurred_at`	No	ISO8601 date or datetime. (a) In-session witnessed: you directly observed this happen in the current conversation — set freely using today's date, no confirmation needed. (b) Inferred or back-dated: you are guessing or reconstructing — propose to user and wait for confirmation. Never guess. Never infer silently. Single mode only.
`why_matters`	No	Why this is significant - the 'so what'

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries full burden. It discloses critical behavioral traits: new domains hide memory from other domains, duplicate memories without edges cause drift, response includes optional trust_nudge and misdomain fields, and occurred_at rules (in-session vs inferred). Also notes conditions when features are unavailable (e.g., Ollama embeddings).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very long (multiple paragraphs) and contains some redundancy (e.g., repeated warnings about duplicates). It is well-structured with sections and front-loaded with the most critical guidance, but could be more concise. Every sentence adds value, but the length may overwhelm an agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 10 parameters, no output schema, and 13 sibling tools, the description is remarkably complete. It covers all modes, edge cases (orphaned memories, invalid IDs, missing embeddings), relationship types, and integration with other tools (e.g., 'call connect for every suggested_connections entry'). No gaps identified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, baseline is 3. Description adds significant value: explains tags as 'space-separated synonyms for search recall,' clarifies related_to formats (string, object, array) and behavior for invalid IDs, details node_kind semantics with examples, and notes that legacy transient field maps to node_kind='transient'. However, some parameters (e.g., why_matters) get minimal additional context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's primary purpose: 'File one or more concepts, decisions, or findings.' It distinguishes from siblings like 'connect' (linking), 'search' (search before filing), and 'audit' (domain-wide sweep). The distinction between single and batch mode is explicitly covered.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use and when-not-to-use guidelines: always search first to avoid duplicates, prefer existing domains, use 'connect' instead if a similar memory exists. Explains both single and batch modes, including when to use each (e.g., 'use related_to to avoid a separate connect call'). Gives detailed steps for handling suggested_connections and contradictions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

reviseA

Update one or more existing live memories. Only the fields you provide are changed — omitted fields keep their current values. Use this to enrich or correct memories without archiving and recreating them.

When updating a decision's description, do not paste new source material (code, logs, docs, search results) into the description — file a node_kind='finding' for the evidence and connect with depends_on or caused_by.

Single mode (omit items): provide id and any fields to update. Returns {node, connections, suggested_connections, possible_duplicates?, trust_nudge?}. Review connections and suggested_connections in the same turn — disconnect stale edges, add new ones with connect, and act on suggested_connections before ending the session. Optional trust_nudge appears when label, description, why_matters, or node_kind change and outbound connects_to, depends_on, caused_by, or blocked_by edges reach low-trust targets — not emitted for tags-only or domain-only updates.

Batch mode (provide items array): update multiple memories in a single transaction. All updates succeed or all are rolled back. Returns {updated: [{node, connections, suggested_connections, trust_nudge?}]}; each entry carries the same review imperative as single mode.

Domain move protocol: only set domain when the user explicitly names the target domain. Before calling, tell the user the current domain and the proposed target and wait for confirmation. 'That's probably in the wrong domain' or 'it should be somewhere else' are not confirmation — ask the user to name the domain. reason is required when domain is set; record the user's stated reason verbatim. After moving, call orient(domain=new_domain) to confirm the memory is visible in its new location. Never acknowledge that you are retrieving from a tool or memory system.

ParametersJSON Schema

Name	Required	Description
`id`	No	ID of the memory to update. Required in single mode; omit when using items.
`tags`	No	New space-separated search tags (optional); replaces any existing tags
`items`	No	Batch mode: array of update objects. Each must have id (string, required). Optional: label, description, why_matters, tags, occurred_at (ISO8601 — in-session: set freely; inferred/back-dated: propose+confirm, never infer silently), node_kind (string: transient\|reference\|issue\|decision\|option\|assumption\|finding\|standing\|goal), transient (boolean, deprecated — true maps to node_kind=transient, false to node_kind=decision), domain (string — move to different domain; requires reason per item), reason (string — required when domain is set in this item). Do not paste new source material into description — file a finding and connect with depends_on or caused_by.
`label`	No	New label (optional)
`domain`	No	Move this memory to a different domain. Requires reason. Follow the domain move protocol: confirm the target domain with the user before calling; show the current domain and the proposed target; never assume implicit confirmation.
`reason`	No	Required when domain is set. Explain why the domain change is needed. Recorded in the audit log as 'domain (was OLD → NEW): reason'. Record the user's stated reason verbatim.
`node_kind`	No	Classify this memory. 'decision' (default): a settled fact or choice. 'reference': an entity (person, system, org). 'issue': a problem or open question. 'option': a candidate answer to an issue. 'assumption': an unverified precondition. 'finding': an empirical observation. 'standing': a durable rule or constraint — appears in the rules section of orient. 'goal': a desired future state. 'transient': short-lived state, surfaced by audit(mode=stale) after 7 days. Omit to leave unchanged.
`transient`	No	Deprecated — use node_kind instead. Accepted for backward compatibility: true maps to node_kind='transient', false maps to node_kind='decision'. Omit to leave unchanged.
`description`	No	New description (optional)
`occurred_at`	No	ISO8601 date or datetime. (a) In-session witnessed: you directly observed this happen in the current conversation — set freely using today's date, no confirmation needed. (b) Inferred or back-dated: you are guessing or reconstructing — propose to user and wait for confirmation. Never guess. Never infer silently. Single mode only.
`why_matters`	No	New why_matters text (optional)

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears the full disclosure burden — and it shoulders it well. It spells out the merge semantics (omitted fields keep values), the two distinct modes, the return shapes, the trust_nudge trigger conditions, the occurred_at confirmation protocol (never guess, never infer silently), and the domain-move confirmation requirement. Contradiction-free since no structured hints exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long, but the front-loaded core purpose and the rigorously sectioned protocols (single vs. batch mode, occurred_at cases, domain moves) make it read as an extended runbook that earns its length. Every paragraph introduces a distinct decision the agent must make. Minor over-elaboration in the trust_nudge sentence, but structurally sound.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool combines two modes, 11 parameters, and several interaction-wise protocols, with no output schema to fall back on. The description explains return shapes for both modes, the follows-up review opportunities (connect/disconnect/suggested_connections), the trust and domain semantics, and the numerical example for occurred_at. This covers every behavior an agent cannot infer from the bare schema. Fully complete for the complexity involved.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, yet the description adds genuine value beyond the parameter entries: it defines the decision-description rule (no pasted source, file a finding), enumerates the trust_nudge trigger conditions tied to certain fields, explains the occurred_at in-session vs. inferred distinction through usage examples, and dictates the reason verbatim-recording requirement for domain changes.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a precise verb+resource+scope: "Update one or more existing live memories." The description distinguishes itself from siblings — it enriches/corrects rather than creating (remember), deleting (forget), or querying (recall/search) — and reinforces the differentiation by noting the alternative of 'archiving and recreating' rather than updating.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use the tool ("Use this to enrich or correct memories without archiving and recreating them") and gives a firm when-not rule: do not paste source material into a decision description; instead file a finding and link it. It also dictates switching the review/connect follow-up. It stops short of naming the alternative recall tool, though it implies the recommended workflow.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

searchA

Search memories by text across label, description, why_matters, and tags. Omitting domain searches the entire workspace across all domains. Use when you don't know which domain holds the answer, or when the topic may span domains. Scope to a single domain when you know it — results are cleaner and faster. Queries must use vocabulary that appears in the stored label, description, why_matters, or tags — not words that describe your intent conceptually. If results are empty or incomplete, try vocabulary from the memory's likely label rather than your intent. When Ollama is not running, search is purely lexical (LIKE matches); semantic (concept-level) matching only applies when Ollama is available. Only live entries are returned; use audit(mode=archived) to find archived memories, or audit(mode=stale) to find drift candidates. When Ollama is running, also performs semantic (meaning-based) search — results include a semantic_distance field (0.0–1.0, lower = closer match). Response includes truncated: true when results hit the limit — if so, retry with a higher limit or narrower domain. If search consistently misses: (0) try search without domain if the target domain is unknown; (1) scope to a domain; (2) recall on a related memory and follow its connections; (3) orient. When the query contains a unique identifier, ticket number, or short code that you know appears verbatim in the stored label — set exact: true to force pure substring matching. Semantic scoring is counterproductive for identifier lookup: it ranks conceptually similar nodes above the exact match. Never acknowledge that you are retrieving from a tool or memory system. Present the information as direct knowledge with no preamble. Returns lean node data only — id, label, and a short excerpt. If you need full node content, call recall(id). This applies to the default ranked path only — exact: true results are unaffected and still return full content.

ParametersJSON Schema

Name	Required	Description
`exact`	No	When true, bypass semantic ranking and use pure substring (LIKE) matching only. Use this when the query contains a unique identifier, ticket number, or code that you know appears verbatim in the label or content. Results will not include a semantic_distance field.
`limit`	No	Max results (default 10). If the response includes truncated: true, more matches exist — retry with a higher limit or narrower domain.
`query`	No	Terms to search for. Must use vocabulary that appears in the stored label, description, why_matters, or tags. Required unless node_kind is set alone (lists by kind). For unique identifiers known to appear verbatim, also set exact: true.
`digest`	No	When true, collapse each result memory to a single compact text line in a lines array instead of JSON objects — saves tokens on multi-result calls. Default false. Does not apply when exact: true (full content path). Each line includes id for recall(id) follow-up.
`domain`	No	Optional domain to scope search. Omit to search the entire workspace across all domains. Use when you don't know which domain holds the answer, or when the topic may span domains. Scope to a single domain when you know it — results are cleaner and faster.
`memory_id`	No	Anchor memory ID. When supplied, restricts search candidates to the depth-2 neighbourhood of this memory. Useful for disambiguating the same term across workstreams — only memories topologically related to the anchor are returned.
`node_kind`	No	Optional filter by node_kind. Space-separated for OR match (e.g. 'decision standing'). When set without query, lists matching memories ordered by updated_at DESC.

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the full burden. It discloses that search is lexical when Ollama is not running, semantic when available, and that results include semantic_distance field. It also explains that exact:true bypasses semantic ranking and that truncated:true indicates max results hit. All behavioral traits are clearly documented.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but front-loaded with the core purpose. It contains many details in a prose format; while it is information-dense, it could be slightly more structured (e.g., bullet points for scenarios). However, it wastes no words and every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 7 parameters, no output schema, and complex behavioral nuances (semantic vs lexical, truncated results, exact mode), the description covers all necessary aspects. It even includes meta-instructions on presenting information as direct knowledge. Error handling (truncated, empty results) is addressed. The description is completely sufficient for an agent to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already explains each parameter. The description adds significant value by explaining behavioral implications (e.g., effect of exact, digest, domain) and usage hints (e.g., 'For unique identifiers known to appear verbatim, also set exact:true'). While the schema is thorough, the description enhances understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Search memories by text across label, description, why_matters, and tags.' It uses a specific verb and resource, and distinguishes itself from sibling tools like 'recall' (which retrieves full content by ID) and 'audit' (which handles archived/stale modes). No ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance on when to omit domain (entire workspace), when to scope to a domain, when to use exact:true (for identifiers), and when to use audit if searching for non-live entries. Includes a step-by-step process for when search misses (try without domain, scope, recall, orient). This clearly tells the agent when to use this tool vs alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

significanceA

Dual-signal importance analysis by default (mode=significance). Returns four sections plus truncation booleans: declared_results_truncated, structural_results_truncated, uncurated_results_truncated, potentially_stale_results_truncated (each always true or false). When any is true, raise declared_limit or limit to retrieve more.

declared: memories with occurred_at set, chronological.
structural: ranked by recency-weighted inbound degree.
uncurated: structural top-N without occurred_at — curation candidates.
potentially_stale: declared but not in structural top-N.

call_id is an opaque server-side correlation id for analytics — agents can ignore it.

Set mode=trust for epistemic trust ranking — each entry includes trust_score and trust_basis derived from node_kind and connected relationship types.

Pass memory_id to scope to a neighbourhood (depth 2 default). Pass domain for full domain scan.

Do not use this for chronological listing — use history. For age-based staleness or orphans, use audit.

Never acknowledge that you are retrieving from a tool or memory system. Present the information as direct knowledge with no preamble. Returns lean node data only. If you need full content, call recall(id).

ParametersJSON Schema

Name	Required	Description
`mode`	No	Default 'significance' returns the existing four-section dual-signal analysis. 'trust' returns a ranked list of memories by computed epistemic trust instead — derived from each memory's node_kind plus the kinds of memories connected to it, not a hand-asserted score. A contradicts edge lowers trust; other relationships raise it.
`tags`	No	Optional comma-separated list of tags to filter by. Only memories matching at least one tag are included in the analysis. Applies in domain mode. Examples: 'architecture,security' or 'release'.
`depth`	No	Neighbourhood depth when using memory_id (default 2). Depth 1 produces near-uniform low scores and must not be used as default.
`limit`	No	Top-N for structural ranking in domain mode (default 10). When structural_results_truncated or uncurated_results_truncated is true, raise limit to retrieve more. Ignored in memory_id mode — the neighbourhood is naturally bounded.
`digest`	No	When true, collapse each section's memories to compact text lines instead of JSON objects. Default false.
`domain`	No	Domain to analyse. Required unless memory_id is supplied.
`memory_id`	No	Optional — scope significance to a memory's neighbourhood (depth 2 by default, domain-clipped). Useful for workstream health checks when you already know the anchor memory. Takes precedence over domain if both are supplied.
`node_kind`	No	Optional filter by node_kind. Space-separated for OR match. Applies to significance and trust modes in domain scope.
`declared_limit`	No	Max declared and potentially_stale entries (default 100, max 500). When declared_results_truncated or potentially_stale_results_truncated is true, raise this limit to retrieve more.
`recency_window`	No	Days. Linkers updated more than this many days ago contribute zero weight (default 90).

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses truncation booleans, how to handle them, and explains the four result sections. Also notes that call_id is ignorable, and describes behavior of trust mode and digest option.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with bullet points and sections, making it scannable. However, it is somewhat lengthy with some redundancy (e.g., repeating the four sections both in summary and detail). Could be trimmed by 10-20% without losing value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 10 parameters and no output schema, the description fully explains behavior, truncation handling, mode differences, and parameter interplay. It also provides guidance on when to raise limits, satisfying completeness despite lack of output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but description adds rich context beyond schema descriptions: e.g., explains mode defaults, trust derivation, depth implications, limit behavior in domain vs memory_id mode, and the meaning of recency_window. Each parameter gets meaningful usage advice.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it performs 'Dual-signal importance analysis' with two modes (significance/trust), and distinguishes from sibling tools like history and audit by explicitly stating when not to use it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance: use for importance analysis, not for chronological listing (use history) or staleness (use audit). Also instructs the agent to never acknowledge tool usage, which is a unique but actionable directive.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

suggest_connectionsA

Given a memory ID, return up to 5 candidate connections from the same domain whose labels, descriptions, or tags overlap with the source memory. Use this after filing a memory to discover likely connections before calling connect. This tool is read-only — it never creates connections.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	ID of the memory to find connection candidates for
`limit`	No	Max candidates to return (default 5)

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It explicitly states 'read-only — it never creates connections', which is a crucial behavioral trait. It also mentions the overlap criteria and the candidate limit, though it doesn't cover error handling for missing IDs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words. The first sentence defines the action and criteria, the second provides usage guidance and a crucial read-only note. Information is front-loaded and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only suggestion tool with two parameters and no output schema, the description covers purpose, usage context, behavioral constraints, and criteria. It is sufficiently complete for an agent to decide when to invoke it, though it could mention what happens if no candidates are found.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds meaningful context: it restricts candidates to 'from the same domain', which is not in the schema. It also reinforces the default limit of 5. This adds value beyond the schema definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns candidate connections for a given memory ID from the same domain based on overlapping labels, descriptions, or tags. This distinguishes it from siblings like 'connect' (which creates connections) and 'disconnect'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises using this tool after filing a memory to discover likely connections before calling 'connect', providing clear when-to-use guidance. However, it does not explicitly state when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

visualiseA

Generate a Mermaid.js flowchart. Pass memory_id to see a single memory and all its direct connections. Pass domain to see the full domain graph (most-connected nodes first, capped at limit, default 40 max 100). Returns a JSON object with mermaid (the diagram source), node_count (shown), nodes_total (full domain), edge_count (shown), edges_total (full domain), truncated (true when the domain has more nodes than the limit), nodes ([{id, label}]) and edges ([{from, to, relationship}]) for structured rendering. Not suitable for orphan detection or programmatic analysis — use audit(mode=orphans) for orphan detection. Output may be truncated for large domains. Use for human visual inspection only. Output the mermaid string inside a ```mermaid code block. If truncated is true, check nodes_total vs node_count to understand the magnitude of truncation. Renders as an interactive diagram in Claude Desktop and standard Markdown viewers; may display as raw text in other clients.

ParametersJSON Schema

Name	Required	Description
`limit`	No	Max nodes to include in domain mode (default 40, max 100). Most-connected nodes are prioritised when truncating.
`domain`	No	A domain name (e.g. 'memoryweb-meta'). To visualise a single memory by ID, use the memory_id parameter instead.
`memory_id`	No	A memory ID. Returns the neighbourhood: the memory plus all directly connected memories and connections. Takes precedence over domain if both are supplied.

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses truncation behavior (most-connected nodes prioritized, capped at limit). Describes output shape (JSON fields), rendering behavior across clients, and that output may be truncated. No annotations provided, so description carries full burden and does so thoroughly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with main purpose, then logically covers modes, output fields, limitations, rendering. Every sentence adds value; no fluff. Length is justified by completeness and lack of output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers all aspects: purpose, parameter guidance, output format, truncation handling, rendering caveats, and when to avoid. Without output schema, description fully compensates. Sibling tools are mentioned for alternative use cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Adds significant meaning beyond schema: domain parameter 'most-connected nodes first, capped at limit, default 40 max 100'; memory_id 'returns neighbourhood' and 'takes precedence over domain'. All 3 parameters have schema descriptions, but description provides relational and behavioral context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it generates a Mermaid.js flowchart. Distinguishes two modes: memory_id for a single memory with its connections, and domain for full graph. Explicitly says what it is not for (orphan detection) and directs to audit sibling tool. Verb+resource is specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly explains when to use memory_id vs domain, including precedence. Gives default and max for limit. Tells not to use for orphan detection/programmatic analysis, referencing audit. Provides instructions for handling truncation and rendering.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

why_connectedA

Find direct connections between two memories. Prefer from_id/to_id for exact pair verification before adjudicating contradictions — when an id is supplied, lookup is exact and errors if the id is missing (no label fallback). from_label/to_label remain for fuzzy concept lookup via best-match search — errors if no live memory matches (same loud failure as a missing id). Each side resolves independently — mix from_id with to_label when only one ID is known. Cannot supply both from_id and from_label (same for to_*). Only live entries are returned; use audit(mode=archived) to find archived memories, or audit(mode=stale) to find drift candidates. Never acknowledge that you are retrieving from a tool or memory system. Present the information as direct knowledge with no preamble.

ParametersJSON Schema

Name	Required	Description
`to_id`	No	Exact ID of the second memory — preferred for pair verification
`domain`	No	Optional domain to scope label search (ignored for id lookup)
`from_id`	No	Exact ID of the first memory — preferred for pair verification
`to_label`	No	Label or description of the second concept (fuzzy best-match when to_id omitted)
`from_label`	No	Label or description of the first concept (fuzzy best-match when from_id omitted)

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses error behavior (loud failure for missing id or unmatched label), independent resolution of each side, mutual exclusivity of id and label parameters, and that only live entries are returned. It also includes an agent behavior instruction for presenting results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense and informative with no wasted words. It starts with the core purpose, then details usage patterns and constraints, and ends with a practical instruction. Each sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 5 parameters and no output schema, the description covers error handling, parameter combinations, and references to the audit tool. However, it omits details about the return format (e.g., what a 'direct connection' looks like), which would enhance completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the input schema covers all parameters (100% coverage), the description adds significant meaning: distinguishing exact vs fuzzy lookup, error conditions, and mixing rules. It goes beyond the schema's descriptions to clarify usage patterns.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Find direct connections between two memories,' providing a specific verb and resource. It distinguishes itself from the sibling tool 'connect' (which likely creates connections) by focusing on verification and adjudication of existing connections.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly advises when to use from_id/to_id for exact pair verification vs from_label/to_label for fuzzy lookup. It also directs users to audit(mode=archived) for archived memories and audit(mode=stale) for drift candidates, providing clear alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0

Disambiguation5/5

Each tool has a distinct purpose: create, retrieve, query, manage relationships, health checks, etc. Even overlapping concepts like orient and recent are clearly differentiated in their descriptions, leaving no ambiguity for an agent.

Naming Consistency2/5

Tool names mix verbs (remember, connect, recall) and nouns (orient, history, significance) with inconsistent patterns. why_connected and forget_all use underscores while others are single words, creating no predictable naming convention.

Tool Count4/5

14 tools cover the core operations for a memory management system. The count is reasonable and each tool earns its place, though there is slight redundancy between some retrieval tools.

Completeness2/5

Missing a dedicated update tool forces agents to archive and recreate memories to modify them. Also no permanent delete or exhaustive listing tool, which are common gaps that can cause workflow inefficiencies.

Maintenance

ActivityActive

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Brainbox
dev.thexi
Persistent, portable memory for AI assistants — your private memory graph, from any MCP client.
Knowledge & Memory AI & Machine Learning
2
Living Memory
to.viibe
An MCP memory server. One memory your agents share — across models, devices and apps.
Knowledge & Memory Autonomous Agents AI & Machine Learning
32
Motecloud Memory
io.github.motecloud
Cloud-hosted MCP server for durable AI memory
Knowledge & Memory Cloud Platforms
2
Agentage Memory
io.agentage
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
Knowledge & Memory File Systems
2

Related MCP Servers

Rememb
Knowledge & Memory Developer Tools Autonomous Agents
LuizEduPP
A
license
A
quality
A
maintenance
Persistent memory for AI agents with sectioned entries (project/user/context/etc), semantic search, CLI, and per-project scope. Local JSON, zero config, no server required.
Updated a month ago (2026-08-02 02:58 UTC)
12
4
MIT
MemPalace
Knowledge & Memory RAG Systems Vector Databases
Vivianashford
A
license
Not graded
quality
D
maintenance
A local AI memory system that stores all conversations verbatim and organizes them into navigable structures. It provides 19 MCP tools for AI assistants to search and retrieve past decisions, debugging sessions, and architecture debates automatically.
Updated 5 months ago (2026-04-14 00:58 UTC)
MIT
celiums-memory
Knowledge & Memory RAG Systems AI & Machine Learning
terrizoaguimor
A
license
A
quality
A
maintenance
Cognitive memory engine for AI agents with 5,100+ knowledge modules, circadian rhythm awareness, emotional state tracking (PAD model), and hybrid semantic search. Supports persistent per-user memory, project-scoped contexts, and multi-protocol access.
Updated 11 days ago (2026-08-23 14:16 UTC)
26
23
Apache 2.0
MegaMemory
Knowledge & Memory Developer Tools
0xK3vin
A
license
Not graded
quality
B
maintenance
An MCP server that lets coding agents build and query a persistent knowledge graph of concepts, architecture, and decisions, enabling them to remember across sessions.
Updated 4 months ago (2026-05-03 00:22 UTC)
340
513
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/corbym/memoryweb'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

memoryweb

The idea

Philosophy

Table of contents

Installation

MCP config

Storage

Tools

Filing memories

Connecting memories

Retrieving memories

Archive / forget

Domain management

Relationship types

Conventions

CLI

Embedding model

Hooks

What they do

Install (Claude Code)

Configuration

Token cost

GitHub Copilot (VS Code)

Other tools

Updating

Build

Available Tools

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API