Assemble a structured memory recall briefing for agent cold-start or session continuity.

deep_rerank: when True, runs the Qwen3-0.6B / BGE-m3 deep reranker on the relevant-memories section (1-5s extra CPU, best ranking quality). Default False so the briefing is bounded to <100ms. ON APPLE SILICON (MPS) the deep reranker can hang indefinitely in a PyTorch MPS kernel (2026-06-19 incident: PIDs 68335, 10086). If you don't need the best-quality ranking, leave this False. If you do need it and the call hangs, set the MEMORY_RERANKER_DISABLED env var or reranker_disabled = true in memory.toml to fully disable the reranker (falls back to the lightweight weak cross-encoder).

Multi-agent coordination tool for task management, file locking, and messaging.

Actions: create_task: Create a new task claim_task: Reserve a task for this agent update_task_status: Update task status (the primary coordination primitive) release_task: Release a task back to the pool complete_task: Mark task done, share result list_tasks: List tasks for a project lock_file: Acquire exclusive lock on a file unlock_file: Release file lock check_lock: Check if a file is locked send_message: Send message to another agent read_messages: Read pending messages get_project_state: See what others are doing update_project_state: Share what you're doing

Coordination model: Messages are notifications. Task status transitions are the ack. When Agent B reads a message and calls update_task_status, that IS the acknowledgement. No separate ack channel needed.

Record click-through rate feedback for a search result.

G4 fix (2026-06-22): memory_record_ctr_feedback (this tool) and memory_reinforce (mcp_memory.py) record two different signals on purpose — they are not interchangeable.

• memory_record_ctr_feedback records the implicit signal: "the user saw this result in the response." Writes a row to ctr_feedback with action=returned/clicked/etc. The search re-ranker reads this table to adjust ranking over time. Use this when a search result is delivered to the user, regardless of whether the user does anything with it.

• memory_reinforce records the explicit signal: "the user judged this memory useful (or not)." Updates success_score and recomputes fitness_score. Use this when a user acts on a memory — e.g. cites it in a lesson, marks a decision as right, or undoes a save because the memory was wrong. Skipping memory_reinforce on every "user saw it" event would over-credit the success score.

In short: record_ctr_feedback = "delivered to user", reinforce = "user acted on it positively". Call both when a user follows up on a search hit. Call only record_ctr_feedback when the user just sees the result. Call only reinforce when the success/failure signal comes from outside the search path (e.g. a downstream agent confirms the memory was correct).

Comprehensive system health: green/yellow/red with actionable next steps.

Consolidates 6 health dimensions into one response:

• Database: accessibility, schema, vec index drift

• Search: semantic search probe

• Worker: background worker liveness

• Crons: cron job execution success rate

• Auto-Save: circuit breaker and recent activity

• Disk: free space

Each subsystem returns green/yellow/red with details and action.

Unified health-check: returns a JSON dict summarising subsystem state.

Checks DB availability, row counts, vec-index drift, FTS sync status, connection-pool depth, background-worker liveness, disk space, and CQRS write-journal health.

Manually trigger skill extraction.

P0 fix #5: lets the operator re-run the lower-threshold extractor on a specific memory (memory_id="lessons/foo") or on every memory when memory_id is empty. Uses the cron implementation so the same code path runs in both places.

Args: memory_id: when non-empty, extract a skill from just this single memory. When empty, run the full extraction pass (same as cron_skill_extraction.py). dry_run: when True, count what would be extracted without writing to the DB.

List extracted skills, ordered by hit_count desc.

P0 fix #5: gives the operator a way to inspect what the lower-threshold extractor actually pulled in. The list includes the topic, hit count, last-used timestamp, and a preview of the description so it's easy to spot good vs bad extractions.

Compile a lesson note into a validated executable agent skill rule file in ~/.agents/skills/.

Search memories by semantic + FTS5 hybrid search.

The primary recall tool. Returns ranked memories matching the query. When the CQRS write journal is enabled, pending (not-yet-materialized) entries are also checked and surfaced as a supplement when the main search returns no results.

Args: query: Natural-language search query (required). category: Filter to a category (e.g. "lessons", "decisions"). limit: Max results (default 10). include_global: Include global memories (default True for default agent, scoped for non-default agents). mode: "hybrid" (default), "semantic", "fts", "facts", "graph". belief_status: Filter KG facts by belief status (active, retracted, deprecated, unconfirmed). epistemic_source: Filter KG facts by epistemic source (agent, auto_save, hook, import, cron). fact_type: Filter KG facts by type (observation, agent_inference, external_stated, hypothesis, derived). memory_source: Filter memories by source type ("agent", "auto_save", "import"). Only returns memories whose source file category matches the given type. shared_with_me: If True, also include memories explicitly shared with the current agent (via the shared pool's target_agent_id).

Save a memory note with sensible defaults.

Args: content: The memory content (markdown). category: lessons / decisions / projects / preferences / sessions (default: lessons). title_slug: URL-friendly slug (auto-generated if empty). tags: Optional keyword tags. pinned: Pin to hot tier (default False). importance: 1-5 (default 3). is_global: Save to global memory (default False). safety_wiring: If False, skip prompt-injection scanning (default True). Set to False for legitimate structured content with section headers and requirement keywords that may trigger false positives.

Review beliefs that may need agent attention — low confidence, old, or stale.

Returns a structured list of belief assertions with subject/predicate/object for the agent to confirm, supersede, retract, or reinforce.

Args: min_confidence: Maximum confidence threshold (returns beliefs BELOW this). belief_status: Filter by status (default "active"). older_than_days: Only return beliefs last reviewed more than this many days ago. limit: Max results (default 20).

Review auto-saved tool invocations and promote or discard them.

The agent can list auto-saved notes, then batch-promote them into intentional lessons or decisions with epistemic_source='agent'.

Args: start_date: ISO date filter start (e.g. "2026-06-01"). Empty = no start bound. end_date: ISO date filter end (e.g. "2026-07-01"). Empty = no end bound. action: "list" | "promote" | "discard". note_ids: List of note IDs to promote/discard (required for promote/discard). category: Target category for promotion (default "lessons").

Delete a memory note by ID. Soft-delete by default (recoverable for 30 days).

Args: note_id: The note ID (e.g. "lessons/my-note"). hard: If True, permanently delete immediately (default False). confirm: Required to be True to allow a hard (permanent) delete. This is a safety gate: hard deletes cannot be recovered, so they must be explicitly confirmed. Soft-deletes (hard=False, the default) are unaffected.

Recall context for the current session or a named thread.

Combines session_start + recall_context into one call. If no query is given, returns recent session activity.

Args: query: What to recall (default: recent activity). session_id: Specific session/thread to recall.

CRUD operations on a specific memory note.

Sprint 2 additions: patch, revert_supersede actions + rationale capture.

Args: note_id: The note ID (e.g. "lessons/my-note"). action: "read" | "update" | "delete" | "restore" | "supersede" | "patch" | "revert_supersede". content: New content (required for update). category: New category (for update). title_slug: New slug (for update/supersede target). tags: New tags (for update). rationale: Reason for the action (required for supersede, patch, revert_supersede; recommended for delete). additions: Text segments to insert (for patch action). deletions: Text segments to remove by content match (for patch action).

Save a lesson or compile a skill from content.

Auto-categorizes and tags the memory. Optionally compiles a skill.

Args: content: The lesson/skill content. as_skill: If True, compile as a skill (default False). skill_name: Skill directory name (required if as_skill=True). category: Target category (default: lessons). tags: Additional tags.

Review recent memory activity, errors, and system health.

Combines audit_query + circuit_breaker_status into one call.

Args: hours: Look back window (default 24h). limit: Max results (default 20). include_errors: Include error entries (default True).

Run safe memory maintenance batch.

Targets: safe_default: compact + consolidate + rewrite_links full: safe_default + backfill + dedup + purge_expired compact: FTS5 compact only dedup: KG entity dedup only

Args: target: Which batch to run (default: safe_default). dry_run: Preview without changes (default False). confirm: Required when target='full' and dry_run=False (purge is destructive).

Share memories with other agents or view shared pool.

Args: note_id: Memory to share (required for action=share). share_with: Target agent ID (for action=share). action: "list" | "share" | "import" | "stats".

Explore the knowledge graph.

Args: query: Natural language KG query (for action=explore). start: Starting entity/node ID (for action=traverse). edge_patterns: Edge type filter (for action=traverse). max_depth: Max traversal depth (default 2). action: "explore" | "traverse" | "shortest_path" | "stats".

View user profile, agent scopes, ARC stats, and cached skills.

Args: action: "stats" | "user" | "agents" | "skills" | "arc". agent_id: Agent ID (for action=agents).

List revision-log entries for a memory or across the store.

Surfaces supersede / amend / revert / delete events recorded in memory_revision_log so the operator can audit what changed.

Args: memory_id: Filter to a specific memory id (empty = all). limit: Max results (default 20). revision_type: Filter by type: supersede, amend, revert, delete (empty = all types).

Retrieve the session startup briefing.

Args: query: Optional topic to scope the briefing to.

Power user escape hatch — pass through to any memory_maintenance operation.

Use this when a verb doesn't cover your use case.

Args: operation: Any memory_maintenance operation name. tenant_id: Tenant identity for tenant-scoped operations. **kwargs: Operation-specific parameters.

Security: this delegates to memory_maintenance, so the confirmation gate on destructive operations applies here too. A destructive op (e.g. purge_expired, okf_export, crdt_sync) called without confirm=True is refused; pass confirm=True to proceed.