Skip to main content
Glama
deenesjakoruzh
EremesNG

Thoth-Mem

by EremesNG
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

thoth-mem

Persistent memory your coding agents can share — and you can audit.

Local, SQLite-first memory for OpenCode, Codex, Claude Code, and Pi. Six focused MCP tools. Zero model calls required.

npm version CI status Node.js 22.12 or newer MIT license

Overview • Install • How it works • Use • Tools • Benchmarks • Runtime • Development

WARNING

thoth-mem is under active development. Core concepts, memory protocols, and integration contracts are still evolving. Expect major breaking changes before a stable release.

91.9%

6

4

0

LongMemEval-S RecallAny@5

focused MCP tools

native harnesses

model calls required

Why thoth-mem

Coding agents lose the decisions that matter between sessions: why an approach was chosen, which failure already occurred, what the next safe action is, and which evidence supports the current answer. Static instruction files help with rules, but they do not provide temporal history, scoped retrieval, or attributable provenance.

thoth-mem gives every supported harness one durable local memory without turning memory into an opaque second agent.

Design choice

What it gives you

SQLite is the source of truth

One local, inspectable ledger with rebuildable FTS5 retrieval.

Evidence before memory

Immutable supporting records remain separate from promoted conclusions.

Temporal history

Corrections and supersession preserve how project knowledge changed.

Progressive retrieval

Start compact, expand context only when useful, fetch full records last.

Scoped identity

Projects and root sessions are explicit; memory does not guess ownership.

A deliberately small API

Six workflow-level MCP tools instead of a sprawling CRUD surface.

NOTE

No embedding model, vector extension, graph engine, LLM, network service, HTTP server, or dashboard is required.

Related MCP server: LumenCore

Install

Requirements: Node.js >=22.12.0 and a supported harness. Pi setup has no version allowlist or upper version limit: it checks package-manager capabilities and verifies the installed extension and resources. New Pi releases do not require a version override. The reproducible SDK test baseline is @earendil-works/pi-coding-agent 1.0.1; passing setup is not certification of every runtime behavior on future releases.

thoth-mem installs memory tooling and lifecycle integration—not agents or subagents. Add --plan --json to any managed npx setup command to preview its changes without writing.

Harness

Native integration

Install

Claude Code

Marketplace plugin, native hooks, six-tool MCP registration, and memory skill

claude plugin marketplace add https://github.com/EremesNG/thoth-plugins.git --scope userclaude plugin install thoth-mem@thoth-plugins --scope userManaged: npx --yes thoth-mem@latest setup claude

Codex CLI

Marketplace plugin, native hooks, six-tool MCP registration, and memory skill

codex plugin marketplace add https://github.com/EremesNG/thoth-plugins.gitcodex plugin add thoth-mem@thoth-pluginsManaged: npx --yes thoth-mem@latest setup codex

OpenCode

Native npm plugin, lifecycle adapter, six-tool MCP surface, and memory skill

npx --yes thoth-mem@latest setup opencode

Pi

Native package extension, lifecycle adapter, and one package-relative six-tool MCP child

npx --yes thoth-mem@latest setup pi

IMPORTANT

Managed setup is global/user-native, idempotent when already current, and requests a host restart after a changed install. Project-scoped copied bundles, broad manager-cache edits, legacy fallback, and fragment migration are intentionally unsupported.

How it works

flowchart LR
  subgraph Hosts[Native harnesses]
    O[OpenCode]
    C[Codex]
    A[Claude Code]
    P[Pi]
  end

  O & C & A & P --> H[Lifecycle adapters]
  H --> S[MemoryService]
  S --> L[(Immutable SQLite ledger)]
  S --> F[(Rebuildable FTS5 index)]
  L & F --> R[Bounded progressive context]
  R --> O & C & A & P

  1. Native adapters map each harness into the same project and root-session contract.

  2. Evidence is immutable; session events receive a database-ordered sequence.

  3. Observations stay outside durable memory until a verified review accepts them and an explicit promotion materializes the proposed memory.

  4. Recall combines project isolation, temporal truth, lexical ranking, and a strict character budget.

  5. Every harness receives the same bounded context without introducing another model into the loop.

IMPORTANT

thoth-mem never silently promotes an observation into durable memory. Rejection is terminal, corrections append successors, and provenance remains available through stable IDs.

Use the memory

Retrieve progressively

mem_recall mode=compact
        ↓
mem_recall mode=context  or  mem_context
        ↓
mem_get only for selected stable IDs

Choose tools by intent

Intent

Tool

Save evidence or durable knowledge

mem_save

Find current or historical project memory

mem_recall

Recover a bounded project or session briefing

mem_context

Expand one selected record and its lineage

mem_get

Inspect timelines, summaries, observations, or project state

mem_project

Record verified root lifecycle events and supported summaries

mem_session

The MCP server exposes exactly these six tools. OpenCode additionally exposes the read-only native thoth_mem_root_identity tool; it is session metadata, not a memory operation.

  • Use mem_project with action=timeline when you need to understand how promoted knowledge changed, rather than which memories best match a query.

  • At checkpoint_pre_compact or finalize, mem_session can validate and version an externally produced summary whose claims cite in-range evidence from the same project and root session. The core never generates that summary.

  • Observation candidates remain outside memory and FTS until a verified root review accepts them and a separate explicit promotion materializes their exact proposed memory.

LongMemEval-S

The public results use the immutable cleaned LongMemEval-S corpus and its 470 eligible non-abstention questions. The runtime remains lexical and local: no embeddings, models, or evaluation-time network calls.

Lexical strategy

RecallAny@5

Recall@5

RecallAll@5

NDCG@10

MRR

Retrieval p95

Role

all-prefix-v1

61/470 (13.0%)

9.8%

6.6%

0.1045

0.1287

1.1471 ms

Archived control

any-prefix-v1

388/470 (82.6%)

67.7%

54.0%

0.6965

0.7947

1.4437 ms

Bounded candidate

all-then-any-prefix-v1

446/470 (94.9%)

87.9%

78.7%

0.8538

0.8717

3.9512 ms

Broad quality reference

strict-selected-any-cap5-rrf-v1

419/470 (89.1%)

79.7%

68.3%

0.7700

0.8177

2.0552 ms

Archived E0 candidate

strict-selected-any-cap5-stable-v1

432/470 (91.9%)

84.8%

75.5%

0.8165

0.8538

9.3504 ms

Current default

  • RecallAny@5: questions with at least one gold session in the first five results.

  • Recall@5: fractional coverage across all gold sessions.

  • RecallAll@5: questions whose every gold session appears in the first five.

  • NDCG@10 / MRR: ranking quality and first-gold position.

  • Retrieval p95: environment-sensitive; compare latency only within the same report.

The first four rows come from the immutable Top-5 lexical comparison. The current-default row comes from the passing stable optimization round, which preserved complete ordered output while reducing p95 by 28.3% from its stable baseline. Every listed run records zero errors and zero model, LLM, or evaluation-time network calls.

The dataset is pinned to revision 98d7416c24c778c2fee6e6f3006e7a073259d48f and SHA-256 d6f21ea9d60a0d56f34a05b609c79c88a451d2ae03597821ea3d5a9678c3a442. Evaluation runs offline through the real built MemoryService, with one isolated SQLite database per question. Gold IDs and oracle data never enter indexed text or ranking.

Protocol sources: LongMemEval repository, official cleaned dataset, and pinned dataset revision.

Runtime data and migration

All harnesses resolve one data directory in this order: an explicit command value, THOTH_MEM_DATA_DIR, strict provider configuration, then ~/.thoth-mem. The database is always memory.sqlite inside the selected directory.

The provider file lives below XDG_CONFIG_HOME/thoth-mem/config.json when XDG configuration is set, or below ~/.config/thoth-mem/config.json otherwise. Malformed, unreadable, schema-invalid, or missing-runtime configuration fails closed.

Opening a revision-9 database with the Pi-capable runtime performs the one-time revision-10 migration. It retains or creates memory.sqlite.pre-v10.bak, takes an immediate write-excluding lock, rechecks the live state against that backup, and rebuilds only the sessions harness constraint. Existing sessions, evidence, events, summaries, receipts, and FTS rows are preserved; a mismatched backup or source drift fails closed before mutation.

Stop every process that may hold the target database, then import the conventional ~/.thoth/thoth.db:

thoth-mem import-legacy

For a nonstandard source or explicit mapping:

thoth-mem import-legacy --source ./legacy.sqlite --map ./mapping.json --data-dir ./current-memory
thoth-mem import-legacy --json

The importer fingerprints its inputs, creates a verified backup and isolated candidate when needed, and publishes only after integrity checks pass. Keep the legacy database, verified backup, and recovery bundle until the migrated runtime has been independently validated.

Development

Clone, build, local host wiring, verification, benchmark reproduction, and repository layout live in the development guide.

Task-specific engineering, persistence, privacy, lifecycle, and testing guidance starts at the agent context index.

Available Tools

6 tools
mem_contextC

Build bounded handoff-first continuity. project_key is always required. Supply both root_session_key and harness for session context, or omit both for project context.

ParametersJSON Schema
NameRequiredDescriptionDefault
harnessNoNative harness for root_session_key; supply both for session context, or omit both for project context.
project_keyYesExact opaque project_key copied verbatim from verified native identity; never derive it from a display name, path hint, remote, branch, worktree name, host ID, listing, or recalled content.
budget_charsNo
correlation_idNo
finalize_answerNo
root_session_keyNoOptional verified root session key; supply with harness for session context, or omit both for project context.

TDQS

C2.7/5.0
Behavior2/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. 'Build' suggests some construction/side effect, but the description never says whether this reads or writes, what gets persisted, whether auth is required, or how budget_chars bounds output. Only the parameter pairing rule is disclosed.

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?

Three short sentences, front-loaded with purpose and immediately followed by the required-parameter and mode rules. Efficient, with only the opening jargon phrase costing clarity.

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

Completeness2/5

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

For a 6-parameter tool with no annotations and no output schema, the description covers only the identity params. It says nothing about budget_chars, correlation_id, finalize_answer, or the shape of what comes back, so an agent cannot call it confidently.

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

Parameters2/5

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

At 50% schema coverage, the description must compensate, and it only reinforces project_key (always required) and the root_session_key/harness pairing – both already documented in the schema. budget_chars, correlation_id, and finalize_answer receive no explanation in either place, leaving half the surface opaque.

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

Purpose3/5

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

The verb+object phrase 'Build bounded handoff-first continuity' conveys a sense of producing continuity context, but 'bounded handoff-first continuity' is jargon that never plainly states what the tool actually returns or does. Nothing distinguishes it from siblings like mem_session, mem_project, or mem_recall.

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

Usage Guidelines3/5

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

It does specify a mode rule: supply both root_session_key and harness for session context, or omit both for project context. But this is parameter-shape guidance, not tool-selection guidance – it never says when to reach for mem_context over mem_recall or mem_session, so usage is only implied.

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

mem_getA

Expand one selected memory, summary, observation, or evidence id returned by a prior tool result. Set history:true to include predecessor lineage for memory, summary, or observation records; evidence ids return evidence without lineage.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesMemory, summary, observation, or evidence id returned by a prior tool result.
historyNoSet true to expand predecessor lineage for memory, summary, or observation records; evidence ids have no lineage.
correlation_idNo

TDQS

A3.7/5.0
Behavior3/5

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the conditional lineage behavior of history:true and the fact that evidence ids have no lineage, but says nothing about read-only safety, permissions, or what 'expand' actually returns (full record vs. fields).

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 tight sentences with no filler; the core action and its precondition come first, and the second sentence earns its place by covering the history/evidence edge case.

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?

For a read tool with no annotations and no output schema, the description should at minimum say what 'expand' returns and how lineage is presented. It covers the input side adequately but leaves the response shape and correlation_id unexplained.

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 67% and both id and history are already documented in the schema; the description largely restates those semantics (id from prior result, history for lineage) rather than adding syntax or format detail. The undocumented correlation_id is not covered anywhere.

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

Purpose4/5

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

States a specific verb ('Expand') and a precise resource (one memory/summary/observation/evidence id), and the phrase 'returned by a prior tool result' distinguishes it from search-style siblings like mem_recall or mem_context. It does not name an alternative sibling explicitly, so it falls short of full differentiation.

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?

The precondition for use is clear: you must already hold an id produced by a prior tool result, which implicitly routes the agent away from recall/search tools. There are no explicit when-not conditions or named alternatives, but the context is unambiguous.

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

mem_projectA

Inspect project views without mutation. action="list": no fields required. action="timeline": project_key required; optionally since, until, cursor, limit, and budget_chars. action="briefing", "summaries", or "observations": project_key required; optionally supply both root_session_key and harness to select that session's summaries/observations (briefing still includes project-wide memories). action="history": id required from a prior result. temporal filters summaries/observations, not timeline. list returns at most 256 exact aliases per project plus aliasCount and aliasesTruncated metadata.

ParametersJSON Schema
NameRequiredDescriptionDefault
idNoRequired for action="history"; send a record id returned by a prior tool result.
limitNoMaximum items (1-100) for action="timeline" or "observations".
sinceNoOptional inclusive lower ISO-8601 instant for action="timeline" only; must be <= until.
stateNoOptional state filter for action="observations".
untilNoOptional inclusive upper ISO-8601 instant for action="timeline" only; must be >= since.
actionYesInspect project views without mutation. action="list": no fields required. action="timeline": project_key required; optionally since, until, cursor, limit, and budget_chars. action="briefing", "summaries", or "observations": project_key required; optionally supply both root_session_key and harness to select that session's summaries/observations (briefing still includes project-wide memories). action="history": id required from a prior result. temporal filters summaries/observations, not timeline. list returns at most 256 exact aliases per project plus aliasCount and aliasesTruncated metadata.
cursorNoUnchanged nextCursor from a prior mem_project action="timeline" result; keep project_key, since, and until unchanged.
harnessNoNative harness for the optional root_session_key filter; supply both or omit both. Not accepted for action="timeline".
temporalNoFilter summaries/observations: current selects current summary versions or observation correction-chain leaves; history includes older summary versions or selects observation predecessors. Not accepted for action="timeline".
project_keyNoExact opaque project_key copied verbatim from verified native identity; never derive it from a display name, path hint, remote, branch, worktree name, host ID, listing, or recalled content. Required for action="timeline", "briefing", "summaries", or "observations"; not required for "list" or "history".
budget_charsNoOptional aggregate character budget for timeline, briefing, summaries, or observations; timeline clamps a positive integer to 1024-20000 characters.
root_session_keyNoOptional session filter for action="briefing", "summaries", or "observations"; supply with harness or omit both.

TDQS

A3.8/5.0
Behavior4/5

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

With no annotations, the description carries the burden; it explicitly says 'without mutation' (read-only), documents cursor semantics ('unchanged nextCursor'), and states list returns at most 256 aliases plus aliasCount/aliasesTruncated. It omits permissions, rate limits, and error behavior, so 4.

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?

Front-loaded with the tool purpose and then action clauses; no filler sentences. Dense for six actions but appropriately sized, so 4.

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?

The description covers action routing and key constraints, but with no output schema it explains return shape only for action='list' and leaves briefing/summaries/observations/history outputs unspecified. Schema 100% coverage offsets parameter gaps, but return transparency remains incomplete, so 3.

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 description coverage is 100% and the top-level text repeats the action property description rather than adding new parameter meaning. Baseline 3 is appropriate.

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

Purpose4/5

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

States 'Inspect project views without mutation' and enumerates six actions (list, timeline, briefing, summaries, observations, history), which conveys the tool's read-only inspection role. It does not distinguish mem_project from siblings like mem_recall or mem_context, so 4 rather than 5.

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?

Gives action-by-action requirements (project_key required for timeline/briefing/summaries/observations, id for history, optional session filters) and notes temporal filters apply to summaries/observations, not timeline. It lacks when-not-to-use or explicit alternatives, so 4.

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

mem_recallB

Search promoted project memory with a non-empty query before expanding selected records. temporal="current" (default) searches current guidance; temporal="history" includes historical records. mode="compact" (default) returns bounded snippets; mode="context" adds selected memory content.

ParametersJSON Schema
NameRequiredDescriptionDefault
modeNocompact (default) returns bounded snippets; context adds selected memory content.
limitNo
queryYesNon-empty search string for promoted project memory.
temporalNocurrent (default) searches current guidance; history includes historical records.
project_keyYesExact opaque project_key copied verbatim from verified native identity; never derive it from a display name, path hint, remote, branch, worktree name, host ID, listing, or recalled content.
budget_charsNo
correlation_idNo
finalize_answerNo

TDQS

B3.4/5.0
Behavior3/5

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

With no annotations, the description carries the full burden, and it does disclose return behavior: mode='compact' returns bounded snippets versus mode='context' adds memory content, plus what temporal='history' includes. It says nothing about permissions, relevance ranking, pagination, or what limit/budget_chars actually bound, so the behavioral picture is only partial.

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?

Three sentences, front-loaded with the core action and then the two enum defaults; no filler or repetition. It is tight, though the temporal/mode clauses mirror the schema wording rather than adding new information.

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?

For an 8-parameter tool with 50% schema coverage, no annotations, and no output schema, the description covers the search intent and the two enum switches but leaves half the parameters undefined and provides no safety or lifecycle context. It is adequate for a basic invocation but not complete.

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 50% and the description essentially restates the enum semantics already present in the schema for query, temporal, and mode. The four undocumented parameters (limit, budget_chars, correlation_id, finalize_answer) receive no explanation, so the description neither compensates for the coverage gap nor adds meaning beyond structured fields.

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

Purpose4/5

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

States a specific verb and resource ('Search promoted project memory') and scopes it with 'with a non-empty query before expanding selected records', which hints at a search-then-expand workflow. However, it never names the sibling it pairs with (mem_get) or how it differs from mem_context, so differentiation is implied rather than explicit.

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

Usage Guidelines3/5

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

'before expanding selected records' implies the sequencing relative to a retrieval step, and the temporal/mode defaults give some selection context. But there is no explicit when-not guidance and no sibling is named (mem_get, mem_context, mem_session), leaving the agent to infer which memory tool to pick.

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

mem_saveA

Save verified durable decisions, discoveries, failures, conventions, and continuation handoffs. For a direct promoted memory other than a handoff, write memory.content as concise labeled Result, Rationale, Scope, and Caveat / safe action lines. Omit Scope or Caveat / safe action when it does not apply, and never invent details to fill the template. Keep evidence compact and factual. Handoff memories keep the dedicated Objective, Completed, First pending action, Blockers, and Key files/checks format and require a stable workstream topic_key; close a finished handoff by saving its outcome under the same topic_key. Send exactly one branch: evidence (optionally + memory for a direct promoted save; structured evidence with metadata forbids memory and requires event_key plus the session pair), observation (requires event_key; session scope also requires the session pair and coverage), observation_review or observation_promotion (each requires event_key plus the session pair). Supply root_session_key and harness together or omit both.

ParametersJSON Schema
NameRequiredDescriptionDefault
memoryNoPromoted memory for direct evidence only; requires evidence without metadata. Do not combine with observation, observation_review, or observation_promotion.
harnessNoNative harness for root_session_key; supply both or omit both. Required wherever root_session_key is required.
evidenceNoDirect evidence { kind, content }; optionally add memory for a promoted save. Structured metadata forbids memory and requires event_key, root_session_key, and harness.
event_keyNoStable event key for idempotency; required for observation, observation_review, observation_promotion, and evidence with metadata.
observationNoSubmit a supported candidate without promotion; requires event_key. Session scope also requires root_session_key, harness, and coverage.
project_keyYesExact opaque project_key copied verbatim from verified native identity; never derive it from a display name, path hint, remote, branch, worktree name, host ID, listing, or recalled content.
project_nameYesCreation/display metadata only; never participates in project identity equality. Prefer the database-persisted name returned by lifecycle or project output.
root_session_keyNoVerified root session key; supply with harness or omit both. Required for session-scoped observations, observation_review, observation_promotion, and evidence with metadata; blank counts as absent.
observation_reviewNoReview one supported observation; requires event_key, root_session_key, and harness. Send no other operation branch or memory.
observation_promotionNoPromote one accepted observation without new prose; requires event_key, root_session_key, and harness. Send no other operation branch or memory.

TDQS

A4.1/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 and does well: it discloses that structured evidence forbids memory, that a finished handoff is closed by re-saving its outcome under the same topic_key, that root_session_key and harness must be supplied together or omitted together, and that details must never be invented. It stops short of describing idempotency behavior (event_key semantics) or the return/confirmation shape, which would round out the behavioral picture.

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 purpose is front-loaded, but the branch rules are compressed into one very long parenthetical sentence ('Send exactly one branch: evidence (optionally + memory ...), observation (requires event_key; session scope also requires ...) ...') with no bullets or line breaks. For a four-branch mutually-exclusive contract, the prose is denser and harder to parse than the complexity warrants, even though most sentences carry real information.

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 10-parameter, deeply nested, no-annotation tool with no output schema, the description covers the essentials an agent needs: branch selection, the memory/handoff content formats, the session-pair coupling, and the metadata/memory prohibition. It omits confirmation/return behavior and idempotency semantics, but with no output schema those are secondary.

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, but the description adds real meaning beyond the schema: the memory.content template (Result, Rationale, Scope, Caveat / safe action lines with an explicit 'omit when not applicable' rule), the dedicated handoff format, and the stable-topic_key closing rule for handoffs. The cross-parameter coupling constraints (memory only with metadata-free evidence; session pair + coverage for session-scoped observations) are semantics the schema cannot express.

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

Purpose4/5

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

Opens with a specific verb+resource ('Save verified durable decisions, discoveries, failures, conventions, and continuation handoffs'), so the write scope is unambiguous against the read-oriented siblings (mem_get, mem_recall). It does not explicitly name or contrast a sibling, but the save-vs-retrieve distinction is self-evident from the enumerated artifact 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?

Explicitly enumerates the four mutually exclusive branches (evidence, observation, observation_review, observation_promotion) and states 'Send exactly one branch,' with per-branch prerequisites (event_key, session pair, coverage) attached to each. This is as close to a decision tree as a description gets, leaving nothing to inference.

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

mem_sessionA

Record verified root lifecycle events; never use it as an ordinary save. summary is optional and only valid for operation="checkpoint_pre_compact" with kind="checkpoint" or operation="finalize" with kind="final". summary.coverage starts at 1 and its to_sequence must advance the current ending sequence for this session and kind. Each claim's support_ids must be evidence ids from this project_key + root_session_key/harness session inside summary.coverage.

ParametersJSON Schema
NameRequiredDescriptionDefault
contentNo
harnessYesVerified native harness for root_session_key in project_key.
summaryNoOptional only for operation="checkpoint_pre_compact" (kind="checkpoint") or operation="finalize" (kind="final"). coverage starts at 1 and to_sequence must advance the current summary for this session and kind. support_ids must be evidence ids from this project_key + root_session_key/harness session inside coverage. Canonical submission limit: 20000 UTF-16 units.
event_keyYesStable lifecycle event key; retries for the same operation must resend identical content/summary.
operationYesLifecycle operation; summary is allowed only for checkpoint_pre_compact (checkpoint) or finalize (final).
project_keyYesExact opaque project_key copied verbatim from verified native identity; never derive it from a display name, path hint, remote, branch, worktree name, host ID, listing, or recalled content.
project_nameYesCreation/display metadata only; never participates in project identity equality. Prefer the database-persisted name returned by lifecycle or project output.
root_session_keyYesStable verified root session key; required with harness for every operation.

TDQS

A3.8/5.0
Behavior3/5

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

With no annotations, the description must carry the behavioral burden. It discloses important constraints around summary validity, coverage advancement, and support_ids scoping, but omits permissions, side effects, failure behavior, and the meaning of 'verified' lifecycle events.

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 compact and front-loads the core purpose before diving into summary constraints. It avoids filler, though some of its content duplicates the already-detailed schema descriptions.

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?

For a complex lifecycle tool with nested objects and no output schema, the description covers core purpose and summary rules. It is incomplete on operation-specific semantics: enroll, recover, capture_root, and guide_post_compact are not explained, leaving invocation guidance thin for a required enum parameter.

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 description coverage is 88%, so the schema already documents most parameters thoroughly. The description reinforces a few nested constraints around summary, coverage, and support_ids, but adds little beyond what the schema descriptions already state.

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 states a specific verb and resource: recording verified root lifecycle events. It explicitly distinguishes the tool from an ordinary save, which routes the agent away from the sibling mem_save for normal persistence.

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?

It gives a clear exclusion ('never use it as an ordinary save') and specifies exactly when the optional summary payload is valid. However, it does not explain when to choose each lifecycle operation or name alternatives beyond the implicit ordinary-save sibling.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 6 tool updatesv0.5.6
    • Changedmem_context13 fields changed
      • addedInput schema / properties / budget_chars
        Added value: +{
+  "type": "number"
+}
      • addedInput schema / properties / correlation_id
        Added value: +{
+  "type": "string"
+}
      • addedInput schema / properties / finalize_answer
        Added value: +{
+  "type": "boolean"
+}
      • addedInput schema / properties / harness
        Added value: +{
+  "description": "Native harness for root_session_key; supply both for session context, or omit both for project context.",
+  "enum": [
+    "opencode",
+    "codex",
+    "claude",
+    "pi",
+    "mcp",
+    "cli",
+    "import"
+  ],
+  "type": "string"
+}
      • removedInput schema / properties / limit
        Removed value: -{
-  "description": "Number of observations to retrieve (default: 20)",
-  "type": "number"
-}
      • removedInput schema / properties / max_chars
        Removed value: -{
-  "description": "Output character budget; 0 disables the context cap",
-  "minimum": 0,
-  "type": "number"
-}
      • removedInput schema / properties / project
        Removed value: -{
-  "description": "Filter by project name",
-  "type": "string"
-}
      • addedInput schema / properties / project_key
        Added value: +{
+  "description": "Exact opaque project_key copied verbatim from verified native identity; never derive it from a display name, path hint, remote, branch, worktree name, host ID, listing, or recalled content.",
+  "minLength": 1,
+  "type": "string"
+}
      • removedInput schema / properties / recall_query
        Removed value: -{
-  "description": "Optional query to append fused recall evidence without changing base context sections",
-  "type": "string"
-}
      • addedInput schema / properties / root_session_key
        Added value: +{
+  "description": "Optional verified root session key; supply with harness for session context, or omit both for project context.",
+  "minLength": 1,
+  "type": "string"
+}
      • removedInput schema / properties / scope
        Removed value: -{
-  "description": "Filter by scope",
-  "enum": [
-    "project",
-    "personal"
-  ],
-  "type": "string"
-}
      • removedInput schema / properties / session_id
        Removed value: -{
-  "description": "Filter to a specific session",
-  "type": "string"
-}
      • addedInput schema / required
        Added value: +[
+  "project_key"
+]
    • Changedmem_get10 fields changed
      • removedInput schema / properties / after
        Removed value: -{
-  "description": "Timeline observations after the focus item (default: 5)",
-  "maximum": 20,
-  "minimum": 0,
-  "type": "number"
-}
      • removedInput schema / properties / before
        Removed value: -{
-  "description": "Timeline observations before the focus item (default: 5)",
-  "maximum": 20,
-  "minimum": 0,
-  "type": "number"
-}
      • addedInput schema / properties / correlation_id
        Added value: +{
+  "type": "string"
+}
      • addedInput schema / properties / history
        Added value: +{
+  "description": "Set true to expand predecessor lineage for memory, summary, or observation records; evidence ids have no lineage.",
+  "type": "boolean"
+}
      • changedInput schema / properties / id / description
        Previous value: -"Record ID to retrieve, interpreted according to kind"New value: +"Memory, summary, observation, or evidence id returned by a prior tool result."
      • changedInput schema / properties / id / type
        Previous value: -"number"New value: +"string"
      • removedInput schema / properties / include_timeline
        Removed value: -{
-  "description": "Include surrounding observations in the same session",
-  "type": "boolean"
-}
      • removedInput schema / properties / kind
        Removed value: -{
-  "description": "Memory kind to retrieve (defaults to observation)",
-  "enum": [
-    "observation",
-    "prompt"
-  ],
-  "type": "string"
-}
      • removedInput schema / properties / max_length
        Removed value: -{
-  "description": "Max characters to return (default: 50000)",
-  "minimum": 100,
-  "type": "number"
-}
      • removedInput schema / properties / offset
        Removed value: -{
-  "description": "Character offset for large content (default: 0)",
-  "minimum": 0,
-  "type": "number"
-}
    • Changedmem_project26 fields changed
      • changedInput schema / properties / action / description
        Previous value: -"Project view to return"New value: +"Inspect project views without mutation. action=\"list\": no fields required. action=\"timeline\": project_key required; optionally since, until, cursor, limit, and budget_chars. action=\"briefing\", \"summaries\", or \"observations\": project_key required; optionally supply both root_session_key and harness to select that session's summaries/observations (briefing still includes project-wide memories). action=\"history\": id required from a prior result. temporal filters summaries/observations, not timeline. list returns at most 256 exact aliases per project plus aliasCount and aliasesTruncated metadata."
      • changedInput schema / properties / action / enum
        Previous value: -[
-  "list",
-  "summary",
-  "graph",
-  "topics",
-  "topic",
-  "health"
-]New value: +[
+  "list",
+  "timeline",
+  "briefing",
+  "history",
+  "summaries",
+  "observations"
+]
      • addedInput schema / properties / budget_chars
        Added value: +{
+  "description": "Optional aggregate character budget for timeline, briefing, summaries, or observations; timeline clamps a positive integer to 1024-20000 characters.",
+  "type": "number"
+}
      • removedInput schema / properties / continuation
        Removed value: -{
-  "description": "Opaque continuation token returned by graph navigation views",
-  "type": "string"
-}
      • addedInput schema / properties / cursor
        Added value: +{
+  "description": "Unchanged nextCursor from a prior mem_project action=\"timeline\" result; keep project_key, since, and until unchanged.",
+  "maxLength": 4096,
+  "minLength": 1,
+  "type": "string"
+}
      • removedInput schema / properties / focus_node_id
        Removed value: -{
-  "description": "Graph focus node id for navigation=neighborhood, currently obs:<id>",
-  "type": "string"
-}
      • addedInput schema / properties / harness
        Added value: +{
+  "description": "Native harness for the optional root_session_key filter; supply both or omit both. Not accepted for action=\"timeline\".",
+  "enum": [
+    "opencode",
+    "codex",
+    "claude",
+    "pi",
+    "mcp",
+    "cli",
+    "import"
+  ],
+  "type": "string"
+}
      • addedInput schema / properties / id
        Added value: +{
+  "description": "Required for action=\"history\"; send a record id returned by a prior tool result.",
+  "minLength": 1,
+  "type": "string"
+}
      • removedInput schema / properties / include_superseded
        Removed value: -{
-  "description": "Explicit history opt-in; honored by navigation=superseded only",
-  "type": "boolean"
-}
      • changedInput schema / properties / limit / description
        Previous value: -"Maximum items to return"New value: +"Maximum items (1-100) for action=\"timeline\" or \"observations\"."
      • addedInput schema / properties / limit / exclusiveMinimum
        Added value: +0
      • changedInput schema / properties / limit / maximum
        Previous value: -500New value: +100
      • removedInput schema / properties / limit / minimum
        Removed value: -1
      • changedInput schema / properties / limit / type
        Previous value: -"number"New value: +"integer"
      • removedInput schema / properties / max_chars
        Removed value: -{
-  "description": "Response character budget; 0 is supported for action=summary only",
-  "maximum": 20000,
-  "minimum": 0,
-  "type": "integer"
-}
      • removedInput schema / properties / navigation
        Removed value: -{
-  "description": "Graph navigation mode for action=graph; defaults to ledger",
-  "enum": [
-    "ledger",
-    "neighborhood",
-    "lineage",
-    "community",
-    "superseded"
-  ],
-  "type": "string"
-}
      • removedInput schema / properties / observation_id
        Removed value: -{
-  "description": "Observation id for lineage or superseded graph navigation",
-  "exclusiveMinimum": 0,
-  "maximum": 9007199254740991,
-  "type": "integer"
-}
      • removedInput schema / properties / project
        Removed value: -{
-  "description": "Project name. Required except action=list and optional for action=topics or health",
-  "type": "string"
-}
      • addedInput schema / properties / project_key
        Added value: +{
+  "description": "Exact opaque project_key copied verbatim from verified native identity; never derive it from a display name, path hint, remote, branch, worktree name, host ID, listing, or recalled content. Required for action=\"timeline\", \"briefing\", \"summaries\", or \"observations\"; not required for \"list\" or \"history\".",
+  "minLength": 1,
+  "type": "string"
+}
      • removedInput schema / properties / relation
        Removed value: -{
-  "description": "Graph relation filter for action=graph",
-  "enum": [
-    "HAS_TYPE",
-    "IN_PROJECT",
-    "HAS_TOPIC_KEY",
-    "HAS_WHAT",
-    "HAS_WHY",
-    "HAS_WHERE",
-    "HAS_LEARNED"
-  ],
-  "type": "string"
-}
      • addedInput schema / properties / root_session_key
        Added value: +{
+  "description": "Optional session filter for action=\"briefing\", \"summaries\", or \"observations\"; supply with harness or omit both.",
+  "minLength": 1,
+  "type": "string"
+}
      • addedInput schema / properties / since
        Added value: +{
+  "description": "Optional inclusive lower ISO-8601 instant for action=\"timeline\" only; must be <= until.",
+  "minLength": 1,
+  "type": "string"
+}
      • addedInput schema / properties / state
        Added value: +{
+  "description": "Optional state filter for action=\"observations\".",
+  "enum": [
+    "pending",
+    "accepted",
+    "rejected",
+    "promoted"
+  ],
+  "type": "string"
+}
      • addedInput schema / properties / temporal
        Added value: +{
+  "description": "Filter summaries/observations: current selects current summary versions or observation correction-chain leaves; history includes older summary versions or selects observation predecessors. Not accepted for action=\"timeline\".",
+  "enum": [
+    "current",
+    "history"
+  ],
+  "type": "string"
+}
      • removedInput schema / properties / topic_key
        Removed value: -{
-  "description": "Topic key for action=topic or graph filtering",
-  "type": "string"
-}
      • addedInput schema / properties / until
        Added value: +{
+  "description": "Optional inclusive upper ISO-8601 instant for action=\"timeline\" only; must be >= since.",
+  "minLength": 1,
+  "type": "string"
+}
    • Changedmem_recall20 fields changed
      • addedInput schema / properties / budget_chars
        Added value: +{
+  "type": "number"
+}
      • addedInput schema / properties / correlation_id
        Added value: +{
+  "type": "string"
+}
      • removedInput schema / properties / debug
        Removed value: -{
-  "description": "Include retrieval defaults and semantic input sources",
-  "type": "boolean"
-}
      • addedInput schema / properties / finalize_answer
        Added value: +{
+  "type": "boolean"
+}
      • removedInput schema / properties / hyde
        Removed value: -{
-  "description": "Request HyDE query expansion when configured",
-  "type": "boolean"
-}
      • removedInput schema / properties / limit / description
        Removed value: -"Maximum evidence items (default: 5)"
      • removedInput schema / properties / limit / maximum
        Removed value: -20
      • removedInput schema / properties / limit / minimum
        Removed value: -1
      • changedInput schema / properties / mode / description
        Previous value: -"compact returns evidence lines; context includes retrieved text"New value: +"compact (default) returns bounded snippets; context adds selected memory content."
      • removedInput schema / properties / project
        Removed value: -{
-  "description": "Optional project filter",
-  "type": "string"
-}
      • addedInput schema / properties / project_key
        Added value: +{
+  "description": "Exact opaque project_key copied verbatim from verified native identity; never derive it from a display name, path hint, remote, branch, worktree name, host ID, listing, or recalled content.",
+  "minLength": 1,
+  "type": "string"
+}
      • changedInput schema / properties / query / description
        Previous value: -"Recall/search query"New value: +"Non-empty search string for promoted project memory."
      • removedInput schema / properties / scope
        Removed value: -{
-  "description": "Optional scope filter",
-  "enum": [
-    "project",
-    "personal"
-  ],
-  "type": "string"
-}
      • removedInput schema / properties / session_id
        Removed value: -{
-  "description": "Optional session filter",
-  "type": "string"
-}
      • addedInput schema / properties / temporal
        Added value: +{
+  "description": "current (default) searches current guidance; history includes historical records.",
+  "enum": [
+    "current",
+    "history"
+  ],
+  "type": "string"
+}
      • removedInput schema / properties / time_from
        Removed value: -{
-  "description": "Optional inclusive created_at lower bound",
-  "type": "string"
-}
      • removedInput schema / properties / time_to
        Removed value: -{
-  "description": "Optional inclusive created_at upper bound",
-  "type": "string"
-}
      • removedInput schema / properties / topic_key
        Removed value: -{
-  "description": "Optional exact topic_key filter",
-  "type": "string"
-}
      • removedInput schema / properties / type
        Removed value: -{
-  "description": "Optional observation type filter",
-  "enum": [
-    "decision",
-    "architecture",
-    "bugfix",
-    "pattern",
-    "config",
-    "discovery",
-    "learning",
-    "session_summary",
-    "manual"
-  ],
-  "type": "string"
-}
      • changedInput schema / required
        Previous value: -[
-  "query"
-]New value: +[
+  "project_key",
+  "query"
+]
    • Changedmem_save19 fields changed
      • removedInput schema / properties / content
        Removed value: -{
-  "description": "Memory content, prompt text, session summary, or text containing a Key Learnings section",
-  "type": "string"
-}
      • addedInput schema / properties / event_key
        Added value: +{
+  "description": "Stable event key for idempotency; required for observation, observation_review, observation_promotion, and evidence with metadata.",
+  "type": "string"
+}
      • addedInput schema / properties / evidence
        Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "content": {
+          "minLength": 1,
+          "type": "string"
+        },
+        "kind": {
+          "enum": [
+            "root_prompt",
+            "explicit_save",
+            "checkpoint",
+            "handoff",
+            "legacy_prompt",
+            "legacy_observation",
+            "session_summary"
+          ],
+          "type": "string"
+        },
+        "source_ref": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "kind",
+        "content"
+      ],
+      "type": "object"
+    },
+    {
+      "additionalProperties": false,
+      "properties": {
+        "content": {
+          "minLength": 1,
+          "type": "string"
+        },
+        "kind": {
+          "const": "explicit_save",
+          "type": "string"
+        },
+        "metadata": {
+          "additionalProperties": false,
+          "properties": {
+            "observation_validation": {
+              "additionalProperties": false,
+              "properties": {
+                "method": {
+                  "maxLength": 500,
+                  "minLength": 1,
+                  "type": "string"
+                },
+                "observation_id": {
+                  "maxLength": 200,
+                  "minLength": 1,
+                  "type": "string"
+                },
+                "result": {
+                  "enum": [
+                    "passed",
+                    "failed"
+                  ],
+                  "type": "string"
+                }
+              },
+              "required": [
+                "observation_id",
+                "result",
+                "method"
+              ],
+              "type": "object"
+            }
+          },
+          "required": [
+            "observation_validation"
+          ],
+          "type": "object"
+        },
+        "source_ref": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "kind",
+        "content",
+        "metadata"
+      ],
+      "type": "object"
+    },
+    {
+      "additionalProperties": false,
+      "properties": {
+        "content": {
+          "minLength": 1,
+          "type": "string"
+        },
+        "kind": {
+          "const": "handoff",
+          "type": "string"
+        },
+        "metadata": {
+          "additionalProperties": false,
+          "properties": {
+            "observation_review_attestation": {
+              "additionalProperties": false,
+              "properties": {
+                "method": {
+                  "maxLength": 500,
+                  "minLength": 1,
+                  "type": "string"
+                },
+                "observation_id": {
+                  "maxLength": 200,
+                  "minLength": 1,
+                  "type": "string"
+                },
+                "reviewer": {
+                  "maxLength": 200,
+                  "minLength": 1,
+                  "type": "string"
+                },
+                "verdict": {
+                  "enum": [
+                    "accepted",
+                    "rejected"
+                  ],
+                  "type": "string"
+                }
+              },
+              "required": [
+                "observation_id",
+                "verdict",
+                "reviewer",
+                "method"
+              ],
+              "type": "object"
+            }
+          },
+          "required": [
+            "observation_review_attestation"
+          ],
+          "type": "object"
+        },
+        "source_ref": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "kind",
+        "content",
+        "metadata"
+      ],
+      "type": "object"
+    }
+  ],
+  "description": "Direct evidence { kind, content }; optionally add memory for a promoted save. Structured metadata forbids memory and requires event_key, root_session_key, and harness."
+}
      • addedInput schema / properties / harness
        Added value: +{
+  "description": "Native harness for root_session_key; supply both or omit both. Required wherever root_session_key is required.",
+  "enum": [
+    "opencode",
+    "codex",
+    "claude",
+    "pi",
+    "mcp",
+    "cli",
+    "import"
+  ],
+  "type": "string"
+}
      • removedInput schema / properties / kind
        Removed value: -{
-  "description": "Write mode. Defaults to observation",
-  "enum": [
-    "observation",
-    "prompt",
-    "session_summary",
-    "passive_learnings"
-  ],
-  "type": "string"
-}
      • addedInput schema / properties / memory
        Added value: +{
+  "additionalProperties": false,
+  "description": "Promoted memory for direct evidence only; requires evidence without metadata. Do not combine with observation, observation_review, or observation_promotion.",
+  "properties": {
+    "content": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "kind": {
+      "enum": [
+        "decision",
+        "convention",
+        "architecture",
+        "discovery",
+        "failure",
+        "project_structure",
+        "handoff",
+        "preference"
+      ],
+      "type": "string"
+    },
+    "outcome": {
+      "enum": [
+        "unknown",
+        "succeeded",
+        "failed",
+        "mixed"
+      ],
+      "type": "string"
+    },
+    "supersedes_id": {
+      "type": "string"
+    },
+    "title": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "topic_key": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "kind",
+    "title",
+    "content"
+  ],
+  "type": "object"
+}
      • addedInput schema / properties / observation
        Added value: +{
+  "additionalProperties": false,
+  "description": "Submit a supported candidate without promotion; requires event_key. Session scope also requires root_session_key, harness, and coverage.",
+  "properties": {
+    "claim": {
+      "maxLength": 4000,
+      "minLength": 1,
+      "type": "string"
+    },
+    "concepts": {
+      "items": {
+        "maxLength": 200,
+        "minLength": 1,
+        "type": "string"
+      },
+      "maxItems": 16,
+      "type": "array"
+    },
+    "coverage": {
+      "additionalProperties": false,
+      "properties": {
+        "from_sequence": {
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991,
+          "type": "integer"
+        },
+        "to_sequence": {
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991,
+          "type": "integer"
+        }
+      },
+      "required": [
+        "from_sequence",
+        "to_sequence"
+      ],
+      "type": "object"
+    },
+    "files": {
+      "items": {
+        "maxLength": 500,
+        "minLength": 1,
+        "type": "string"
+      },
+      "maxItems": 16,
+      "type": "array"
+    },
+    "generator": {
+      "additionalProperties": false,
+      "properties": {
+        "config_hash": {
+          "pattern": "^[0-9a-f]{64}$",
+          "type": "string"
+        },
+        "kind": {
+          "enum": [
+            "root_agent",
+            "harness",
+            "model"
+          ],
+          "type": "string"
+        },
+        "name": {
+          "maxLength": 200,
+          "minLength": 1,
+          "type": "string"
+        },
+        "version": {
+          "maxLength": 200,
+          "minLength": 1,
+          "type": "string"
+        }
+      },
+      "required": [
+        "kind",
+        "name"
+      ],
+      "type": "object"
+    },
+    "kind": {
+      "enum": [
+        "decision",
+        "constraint",
+        "fact",
+        "procedure",
+        "result",
+        "failure",
+        "preference"
+      ],
+      "type": "string"
+    },
+    "predecessor_id": {
+      "maxLength": 200,
+      "minLength": 1,
+      "type": "string"
+    },
+    "proposed_memory": {
+      "additionalProperties": false,
+      "properties": {
+        "content": {
+          "minLength": 1,
+          "type": "string"
+        },
+        "kind": {
+          "enum": [
+            "decision",
+            "convention",
+            "architecture",
+            "discovery",
+            "failure",
+            "project_structure",
+            "handoff",
+            "preference"
+          ],
+          "type": "string"
+        },
+        "outcome": {
+          "enum": [
+            "unknown",
+            "succeeded",
+            "failed",
+            "mixed"
+          ],
+          "type": "string"
+        },
+        "title": {
+          "minLength": 1,
+          "type": "string"
+        },
+        "topic_key": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "kind",
+        "title",
+        "content"
+      ],
+      "type": "object"
+    },
+    "scope": {
+      "enum": [
+        "session",
+        "project"
+      ],
+      "type": "string"
+    },
+    "support_ids": {
+      "items": {
+        "maxLength": 200,
+        "minLength": 1,
+        "type": "string"
+      },
+      "maxItems": 16,
+      "minItems": 1,
+      "type": "array"
+    },
+    "title": {
+      "maxLength": 500,
+      "minLength": 1,
+      "type": "string"
+    }
+  },
+  "required": [
+    "kind",
+    "scope",
+    "title",
+    "claim",
+    "proposed_memory",
+    "support_ids",
+    "generator"
+  ],
+  "type": "object"
+}
      • addedInput schema / properties / observation_promotion
        Added value: +{
+  "additionalProperties": false,
+  "description": "Promote one accepted observation without new prose; requires event_key, root_session_key, and harness. Send no other operation branch or memory.",
+  "properties": {
+    "observation_id": {
+      "maxLength": 200,
+      "minLength": 1,
+      "type": "string"
+    }
+  },
+  "required": [
+    "observation_id"
+  ],
+  "type": "object"
+}
      • addedInput schema / properties / observation_review
        Added value: +{
+  "additionalProperties": false,
+  "description": "Review one supported observation; requires event_key, root_session_key, and harness. Send no other operation branch or memory.",
+  "properties": {
+    "basis": {
+      "enum": [
+        "root_user_confirmed",
+        "observable_validation",
+        "independent_review"
+      ],
+      "type": "string"
+    },
+    "observation_id": {
+      "maxLength": 200,
+      "minLength": 1,
+      "type": "string"
+    },
+    "policy": {
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "maxLength": 200,
+          "minLength": 1,
+          "type": "string"
+        },
+        "version": {
+          "maxLength": 200,
+          "minLength": 1,
+          "type": "string"
+        }
+      },
+      "required": [
+        "id",
+        "version"
+      ],
+      "type": "object"
+    },
+    "reason": {
+      "maxLength": 1000,
+      "minLength": 1,
+      "type": "string"
+    },
+    "support_ids": {
+      "items": {
+        "maxLength": 200,
+        "minLength": 1,
+        "type": "string"
+      },
+      "maxItems": 16,
+      "minItems": 1,
+      "type": "array"
+    },
+    "verdict": {
+      "enum": [
+        "accepted",
+        "rejected"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "observation_id",
+    "verdict",
+    "basis",
+    "policy",
+    "reason",
+    "support_ids"
+  ],
+  "type": "object"
+}
      • removedInput schema / properties / project
        Removed value: -{
-  "description": "Project name",
-  "type": "string"
-}
      • addedInput schema / properties / project_key
        Added value: +{
+  "description": "Exact opaque project_key copied verbatim from verified native identity; never derive it from a display name, path hint, remote, branch, worktree name, host ID, listing, or recalled content.",
+  "minLength": 1,
+  "type": "string"
+}
      • addedInput schema / properties / project_name
        Added value: +{
+  "description": "Creation/display metadata only; never participates in project identity equality. Prefer the database-persisted name returned by lifecycle or project output.",
+  "minLength": 1,
+  "type": "string"
+}
      • addedInput schema / properties / root_session_key
        Added value: +{
+  "description": "Verified root session key; supply with harness or omit both. Required for session-scoped observations, observation_review, observation_promotion, and evidence with metadata; blank counts as absent.",
+  "type": "string"
+}
      • removedInput schema / properties / scope
        Removed value: -{
-  "description": "Observation scope",
-  "enum": [
-    "project",
-    "personal"
-  ],
-  "type": "string"
-}
      • removedInput schema / properties / session_id
        Removed value: -{
-  "description": "Session ID (default: manual-save-{project})",
-  "type": "string"
-}
      • removedInput schema / properties / title
        Removed value: -{
-  "description": "Short searchable title. Required for kind=observation",
-  "type": "string"
-}
      • removedInput schema / properties / topic_key
        Removed value: -{
-  "description": "Stable key for observation upserts",
-  "type": "string"
-}
      • removedInput schema / properties / type
        Removed value: -{
-  "description": "Observation category for kind=observation",
-  "enum": [
-    "decision",
-    "architecture",
-    "bugfix",
-    "pattern",
-    "config",
-    "discovery",
-    "learning",
-    "session_summary",
-    "manual"
-  ],
-  "type": "string"
-}
      • changedInput schema / required
        Previous value: -[
-  "content"
-]New value: +[
+  "project_key",
+  "project_name"
+]
    • Changedmem_session17 fields changed
      • removedInput schema / properties / action
        Removed value: -{
-  "description": "Session action",
-  "enum": [
-    "start",
-    "summary",
-    "checkpoint"
-  ],
-  "type": "string"
-}
      • removedInput schema / properties / content / description
        Removed value: -"Full session summary for action=summary"
      • removedInput schema / properties / directory
        Removed value: -{
-  "description": "Working directory for action=start",
-  "type": "string"
-}
      • addedInput schema / properties / event_key
        Added value: +{
+  "description": "Stable lifecycle event key; retries for the same operation must resend identical content/summary.",
+  "minLength": 1,
+  "type": "string"
+}
      • addedInput schema / properties / harness
        Added value: +{
+  "description": "Verified native harness for root_session_key in project_key.",
+  "enum": [
+    "opencode",
+    "codex",
+    "claude",
+    "pi",
+    "mcp",
+    "cli",
+    "import"
+  ],
+  "type": "string"
+}
      • removedInput schema / properties / id
        Removed value: -{
-  "description": "Session ID. Required for action=start; defaults to manual-save-{project} for summary/checkpoint",
-  "type": "string"
-}
      • addedInput schema / properties / operation
        Added value: +{
+  "description": "Lifecycle operation; summary is allowed only for checkpoint_pre_compact (checkpoint) or finalize (final).",
+  "enum": [
+    "enroll",
+    "recover",
+    "capture_root",
+    "checkpoint_pre_compact",
+    "guide_post_compact",
+    "finalize"
+  ],
+  "type": "string"
+}
      • removedInput schema / properties / project
        Removed value: -{
-  "description": "Project name",
-  "type": "string"
-}
      • addedInput schema / properties / project_key
        Added value: +{
+  "description": "Exact opaque project_key copied verbatim from verified native identity; never derive it from a display name, path hint, remote, branch, worktree name, host ID, listing, or recalled content.",
+  "minLength": 1,
+  "type": "string"
+}
      • addedInput schema / properties / project_name
        Added value: +{
+  "description": "Creation/display metadata only; never participates in project identity equality. Prefer the database-persisted name returned by lifecycle or project output.",
+  "minLength": 1,
+  "type": "string"
+}
      • addedInput schema / properties / root_session_key
        Added value: +{
+  "description": "Stable verified root session key; required with harness for every operation.",
+  "minLength": 1,
+  "type": "string"
+}
      • addedInput schema / properties / summary / additionalProperties
        Added value: +false
      • changedInput schema / properties / summary / description
        Previous value: -"Short checkpoint summary for action=checkpoint"New value: +"Optional only for operation=\"checkpoint_pre_compact\" (kind=\"checkpoint\") or operation=\"finalize\" (kind=\"final\"). coverage starts at 1 and to_sequence must advance the current summary for this session and kind. support_ids must be evidence ids from this project_key + root_session_key/harness session inside coverage. Canonical submission limit: 20000 UTF-16 units."
      • addedInput schema / properties / summary / properties
        Added value: +{
+  "claims": {
+    "description": "1-32 atomic supported claims; keep the canonical summary within 20000 UTF-16 units.",
+    "items": {
+      "additionalProperties": false,
+      "properties": {
+        "content": {
+          "description": "Atomic claim content; at most 2000 code points after privacy filtering.",
+          "minLength": 1,
+          "type": "string"
+        },
+        "kind": {
+          "enum": [
+            "objective",
+            "completed",
+            "decision",
+            "changed_surface",
+            "verification",
+            "pending",
+            "blocker",
+            "next_action"
+          ],
+          "type": "string"
+        },
+        "outcome": {
+          "enum": [
+            "unknown",
+            "succeeded",
+            "failed",
+            "mixed"
+          ],
+          "type": "string"
+        },
+        "support_ids": {
+          "description": "1-16 distinct evidence ids from this project_key + root_session_key/harness session inside summary.coverage; never memory, summary, or observation ids.",
+          "items": {
+            "maxLength": 200,
+            "minLength": 1,
+            "type": "string"
+          },
+          "maxItems": 16,
+          "minItems": 1,
+          "type": "array"
+        }
+      },
+      "required": [
+        "kind",
+        "content",
+        "support_ids"
+      ],
+      "type": "object"
+    },
+    "maxItems": 32,
+    "minItems": 1,
+    "type": "array"
+  },
+  "coverage": {
+    "additionalProperties": false,
+    "description": "Inclusive session evidence coverage; start at 1 and advance to_sequence for this session and summary kind.",
+    "properties": {
+      "from_sequence": {
+        "description": "Inclusive first session event sequence; must start at 1.",
+        "exclusiveMinimum": 0,
+        "maximum": 9007199254740991,
+        "type": "integer"
+      },
+      "to_sequence": {
+        "description": "Inclusive last session event sequence; must be >= from_sequence and exceed the current summary ending sequence for this session and kind.",
+        "exclusiveMinimum": 0,
+        "maximum": 9007199254740991,
+        "type": "integer"
+      }
+    },
+    "required": [
+      "from_sequence",
+      "to_sequence"
+    ],
+    "type": "object"
+  },
+  "generator": {
+    "additionalProperties": false,
+    "properties": {
+      "config_hash": {
+        "pattern": "^[0-9a-f]{64}$",
+        "type": "string"
+      },
+      "kind": {
+        "enum": [
+          "root_agent",
+          "harness",
+          "model"
+        ],
+        "type": "string"
+      },
+      "name": {
+        "maxLength": 200,
+        "minLength": 1,
+        "type": "string"
+      },
+      "version": {
+        "maxLength": 200,
+        "minLength": 1,
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind",
+      "name"
+    ],
+    "type": "object"
+  },
+  "kind": {
+    "description": "Send checkpoint for operation=\"checkpoint_pre_compact\" or final for operation=\"finalize\".",
+    "enum": [
+      "checkpoint",
+      "final"
+    ],
+    "type": "string"
+  }
+}
      • addedInput schema / properties / summary / required
        Added value: +[
+  "kind",
+  "coverage",
+  "generator",
+  "claims"
+]
      • changedInput schema / properties / summary / type
        Previous value: -"string"New value: +"object"
      • changedInput schema / required
        Previous value: -[
-  "action",
-  "project"
-]New value: +[
+  "operation",
+  "harness",
+  "project_key",
+  "project_name",
+  "root_session_key",
+  "event_key"
+]
  2. 5 tool updatesv0.4.13
    • Addedmem_context
    • Addedmem_get
    • Addedmem_project
    • Addedmem_save
    • Addedmem_session
  3. 5 tool updatesv0.4.1
    • Removedmem_context
    • Removedmem_get
    • Removedmem_project
    • Removedmem_save
    • Removedmem_session
  4. 6 tool updatesv0.3.7
    • First observedmem_context
    • First observedmem_get
    • First observedmem_project
    • First observedmem_recall
    • First observedmem_save
    • First observedmem_session
Deploy Server
Context All Your Agents Can ShareAgents share what they learn, hand off work, and hold it when you switch models. Start with 5 GB free.fulcradynamics.comAd

TDQS

A3.6/5.0

Scored across 6 tools

Disambiguation4/5

Each tool has a distinct role: mem_save writes, mem_get expands a specific id, mem_recall searches, mem_context builds continuity, mem_project inspects views, and mem_session records lifecycle events. However, the retrieval-oriented tools (mem_recall, mem_context, mem_project) overlap conceptually, and mem_save vs mem_session require explicit guidance ('never use it as an ordinary save'), signaling residual ambiguity.

Naming Consistency5/5

All six tools use a consistent mem_ prefix followed by a concise snake_case noun/verb (mem_get, mem_save, mem_recall, mem_context, mem_project, mem_session). The pattern is predictable and uniform throughout.

Tool Count5/5

Six tools is well-scoped for a memory server, covering write, expand, search, context, project inspection, and lifecycle in a compact surface. Each tool clearly earns its place with no redundancy or padding.

Completeness4/5

The surface covers the full memory lifecycle: saving, searching, expanding, context building, project inspection, and session lifecycle recording. A delete/forget or update operation appears absent, a minor gap agents could work around in an append-oriented memory model.

Maintenance

ActivityActive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MCP Vector Memory

    vertexhub-ai
    A
    license
    Not graded
    quality
    Not graded
    maintenance
    Provides AI coding agents with persistent, long-term memory through local semantic search and SQLite storage. It enables agents to save and retrieve architectural decisions or project context across different conversation sessions without requiring cloud services.
    MIT

  • LumenCore

    arclightdynamics
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides AI coding assistants with persistent project memory to retain architectural decisions, code patterns, and domain knowledge across sessions. It stores data locally in a SQLite database, allowing agents to remember, recall, and manage project-specific context using full-text search.
    8 npm
    Apache 2.0

  • Memory MCP

    nerdyaustin
    A
    license
    A
    quality
    B
    maintenance
    Provides persistent cross-session memory and full-text search for AI coding assistants, storing project context, decisions, and preferences while enabling searchable access to conversation history via local SQLite.
    8
    1
    MIT

  • code-recall

    AbianS
    A
    license
    Not graded
    quality
    C
    maintenance
    Gives AI coding agents persistent memory by storing observations, decisions, and learnings in a local SQLite database with vector search, full-text search, and a rules engine.
    4
    MIT