3-verb MCP facade: remember / recall / forget

[ahoward]

3-Verb MCP Facade

Parent: #101 (Hippocampus v2)
Depends on: #102 (JSONL audit trail), #108 (graph-backed recall)
Priority: 2 (the agent-facing interface)

What

Reduce the default MCP tool surface from 50 tools to 3. The existing tools remain available behind an env flag. The default MCP configuration exposes only remember, recall, and forget.

MCP Tool Definitions

remember

{
  "name": "remember",
  "description": "Store a memory. Feed it anything you observed, learned, or decided.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "what": {"type": "string", "description": "What you observed, learned, or decided"},
      "from": {"type": "string", "description": "Where this came from: 'self', 'file://path', 'url://...' (default: self)"},
      "tags": {"type": "array", "items": {"type": "string"}, "description": "Free-form labels (auto-detected if omitted)"}
    },
    "required": ["what"]
  }
}

Internally: Creates concept in graph (with embedding, edges to similar concepts, provenance). Appends to JSONL audit trail.

Returns: {id, what, from, tags, created, connections: [{id, what, score}]}

The connections field shows the top-3 auto-linked existing memories. Immediate feedback: "your new memory is related to these."

recall

{
  "name": "recall",
  "description": "Search your memories. Describe what you need — brane returns relevant memories ranked by meaning, with connections.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "what": {"type": "string", "description": "What you're trying to remember"},
      "limit": {"type": "number", "description": "Max results (default: 10)"},
      "tags": {"type": "array", "items": {"type": "string"}, "description": "Filter by tags"}
    },
    "required": ["what"]
  }
}

Internally: HNSW vector search → graph neighbor traversal → Datalog contradiction detection → strength scoring. The full graph engine powers a single simple call.

Returns: Array of memories, each with:

• id, what, from, tags, created
• strength (relevance score combining similarity + recency + access frequency)
• connections (linked memories from graph edges)
• trust ("high", "medium", "low")
• conflict (true if contradicts another returned result)

forget

{
  "name": "forget",
  "description": "Remove a memory that is wrong or stale.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {"type": "string", "description": "Memory ID to forget (from a previous recall)"}
    },
    "required": ["id"]
  }
}

Internally: Cascade-deletes concept + edges in graph (#96 already does this). Appends tombstone to JSONL.

Returns: {id, forgotten: true}

MCP Prompt: memory-protocol (updated)

You have brane, a memory system. Three operations:

REMEMBER when you learn something surprising, make a decision, discover a pattern,
or encounter something you'll need later. Don't over-remember — if it's in the code,
you don't need to remember it.

RECALL when starting a task (check past experience), hitting an error (seen before?),
or making a decision (what worked last time?).

FORGET when you recall something wrong or outdated.

That's it. Three verbs. Trust the system.

Power Tools

The existing 50 MCP tools remain registered but are NOT listed in the default tools/list response. Available via BRANE_MCP_MODE=full env var.

Acceptance Criteria

• Default MCP tools/list returns exactly 3 tools
• BRANE_MCP_MODE=full returns all 50+ tools
• remember creates graph concept + JSONL entry, returns connections
• recall uses graph engine (HNSW + traversal), returns trust + conflict flags
• forget cascade-deletes from graph + tombstones in JSONL
• Updated memory-protocol MCP prompt
• Existing tests unaffected (power tools still work in full mode)