MCP tools reference
Palimem exposes exactly eleven MCP tools. Every tool listed here is normatively defined in component spec v1.7.0 Section 10. No tools are listed here that are not in the published spec.
Common request fields
Section titled “Common request fields”Every tool call requires a JSON object with at minimum a tool field. Most tools also require scope and namespace:
| Field | Required | Description |
|---|---|---|
tool |
Yes | Exact tool name (e.g. memory_remember) |
scope |
Most tools | user / session / repository |
namespace |
Most tools | Project or session identifier |
Tool 1 — memory_remember
Section titled “Tool 1 — memory_remember”Purpose: Write a memory record to the governed store. Supersedes any existing record with the same subject key.
| Argument | Required | Description |
|---|---|---|
tool |
Yes | memory_remember |
scope |
Yes | user / session / repository |
namespace |
Yes | Project or session name |
topic |
Yes | What the memory is about |
field |
Yes | Specific attribute |
memory_type |
Yes | fact / belief / preference / episode / note |
value |
Yes | The value to store (string or structured object) |
provenance |
Recommended | { source, tool, actor, request_id } |
legal_hold |
No | true blocks memory_forget and retention eviction |
Behavior: Appends a remember or supersede WAL event. Subject key conflict → supersede. Returns success envelope with seq (WAL sequence number).
Tool 2 — memory_search
Section titled “Tool 2 — memory_search”Purpose: Search governed memory by free-text query within a scope and namespace.
| Argument | Required | Description |
|---|---|---|
tool |
Yes | memory_search |
scope |
Yes | Scope to search |
namespace |
Yes | Namespace to search |
query |
Yes | Free-text search query |
limit |
No | Maximum results (default: 10) |
subject |
No | Equality filter: { topic?, field? } |
as_of |
No | ISO 8601 timestamp — recall governed state at this point |
Behavior: Returns ranked results from current semantic units. Never returns a superseded value as current. With as_of, reconstructs state from the WAL at the given timestamp.
Tool 3 — memory_get
Section titled “Tool 3 — memory_get”Purpose: Direct subject-key lookup. Returns the current (or historical) value for a specific memory subject.
| Argument | Required | Description |
|---|---|---|
tool |
Yes | memory_get |
scope |
Yes | Scope |
namespace |
Yes | Namespace |
topic |
Yes | Topic |
field |
Yes | Field |
memory_type |
Yes | Memory type |
as_of |
No | ISO 8601 — point-in-time recall |
depth |
No | shallow (current only) / full (include history) |
Behavior: Returns the current value or not_found. With as_of, reconstructs from WAL. No match returns error.code = not_found.
Tool 4 — memory_forget
Section titled “Tool 4 — memory_forget”Purpose: Retract a memory subject. Appends a retract WAL event rather than deleting history.
| Argument | Required | Description |
|---|---|---|
tool |
Yes | memory_forget |
scope |
Yes | Scope |
namespace |
Yes | Namespace |
topic |
Yes | Topic |
field |
Yes | Field |
memory_type |
Yes | Memory type |
Behavior: Appends retract event. After retraction, memory_get returns not_found and memory_search skips the subject. If subject has legal_hold: true, returns error.code = legal_hold.
Tool 5 — memory_status
Section titled “Tool 5 — memory_status”Purpose: Report integration status, tool count, and operator metadata for a scope and namespace.
| Argument | Required | Description |
|---|---|---|
tool |
Yes | memory_status |
scope |
Yes | Scope |
namespace |
Yes | Namespace |
Behavior: Returns namespace operator metadata per spec Section 10.5: wal_high_water_seq, semantic_units_in_sync, index_status, consolidation, review_queue, profile_engine, pii_scan, retention, and fleet when configured.
Use this tool to verify the store is healthy after tools/list confirms eleven tools are registered. Expect ok: true and index_status.state: "current".
Tool 6 — memory_consolidate
Section titled “Tool 6 — memory_consolidate”Purpose: Deduplicate redundant units, summarize low-salience noise clusters, and produce promotion proposals.
| Argument | Required | Description |
|---|---|---|
tool |
Yes | memory_consolidate |
scope |
Yes | Scope |
namespace |
Yes | Namespace |
dry_run |
No | true to preview proposals without applying |
Behavior: Deduplicates and summarizes. Does not remove facts under legal hold or current semantic units. Proposals require memory_review accept to become current state. Returns error.code = consolidation_unavailable when unsupported.
Tool 7 — memory_review
Section titled “Tool 7 — memory_review”Purpose: Review and accept or reject consolidation proposals. Controls the promotion gate from belief to fact.
| Argument | Required | Description |
|---|---|---|
tool |
Yes | memory_review |
scope |
Yes | Scope |
namespace |
Yes | Namespace |
action |
Yes | export / accept / reject / list |
proposal_id |
For accept/reject | ID of the proposal to act on |
Behavior: export produces a review report. accept promotes a proposal to current state. reject discards it. Returns error.code = review_unavailable when unsupported.
Tool 8 — memory_profile
Section titled “Tool 8 — memory_profile”Purpose: Assemble a bounded user-profile manifest for injection into agent context.
| Argument | Required | Description |
|---|---|---|
tool |
Yes | memory_profile |
scope |
Yes | Scope (typically user) |
namespace |
Yes | Namespace |
budget_tokens |
No | Maximum token budget for the manifest |
depth |
No | shallow (preferences only) / full (preferences + beliefs + session summaries) |
Behavior: Returns a bounded Markdown manifest with sections (preference records) and citations. Truncates deterministically to budget_tokens. Empty store returns empty success (not error).
Tool 9 — memory_reflect
Section titled “Tool 9 — memory_reflect”Purpose: Synthesize governed evidence with citations. Uses the configured LLM adapter to produce a grounded synthesis.
| Argument | Required | Description |
|---|---|---|
tool |
Yes | memory_reflect |
scope |
Yes | Scope |
namespace |
Yes | Namespace |
query |
Yes | The question or topic to synthesize |
limit |
No | Maximum evidence records to consider |
Behavior: Searches governed memory, assembles evidence, synthesizes with citations. Each citation includes scope, namespace, topic, field, memory_type, seq, event_id. Never performs silent WAL writes. Returns error.code = reflection_unavailable when LLM adapter is unavailable.
Tool 10 — memory_query_temporal
Section titled “Tool 10 — memory_query_temporal”Purpose: Return a belief trajectory — the ordered sequence of governed values for subjects matching scope filters across one or more audit points.
| Argument | Required | Description |
|---|---|---|
tool |
Yes | memory_query_temporal |
scope |
Yes | Scope |
namespace |
Yes | Namespace |
topic |
No | Filter by topic |
field |
No | Filter by field |
from |
No | ISO 8601 start timestamp |
to |
No | ISO 8601 end timestamp |
include_retracted |
No | Include retraction events in trajectory |
Behavior: Returns ordered trajectory entries with seq, value, event (remember / supersede / retract), and timestamp. Extends as_of lookup to multi-subject, multi-point queries. Returns error.code = temporal_query_unavailable when unsupported.
Tool 11 — memory_audit_export
Section titled “Tool 11 — memory_audit_export”Purpose: Export operator audit records for compliance review.
| Argument | Required | Description |
|---|---|---|
tool |
Yes | memory_audit_export |
scope |
Yes | Scope |
namespace |
Yes | Namespace |
from |
No | ISO 8601 start timestamp |
to |
No | ISO 8601 end timestamp |
format |
No | jsonl (default) / json |
Behavior: Exports full WAL with provenance metadata (source, tool, actor, request_id), timestamps, legal hold flags, and supersession chains. Returns error.code = audit_export_unavailable when unsupported.
Error codes
Section titled “Error codes”| Code | Meaning |
|---|---|
not_found |
Subject has no value at the requested recall point |
legal_hold |
memory_forget or retention eviction blocked by legal hold |
invalid_request |
Missing required field or invalid argument |
consolidation_unavailable |
memory_consolidate not supported |
review_unavailable |
memory_review not supported |
profile_unavailable |
memory_profile cannot run |
reflection_unavailable |
memory_reflect LLM adapter unavailable |
temporal_query_unavailable |
memory_query_temporal not supported |
audit_export_unavailable |
memory_audit_export not supported |
Traceability
Section titled “Traceability”All eleven tools are normatively defined in component spec v1.7.0 Section 10 (Sections 10.1–10.11). This reference page summarizes observable behavior; the spec is authoritative.
143 component tests cover the tool surface. Spec version: 1.7.0.