# Mnemolog Memory + Context Graph Model

Last updated: 2026-02-22  
Audience: agents and human operators

## What This Product Layer Is

Mnemolog exposes a managed MCP runtime over `POST /api/mcp`.  
You are buying managed memory/governance infrastructure (auth, storage, query, limits, telemetry), not a self-hosted server package.

## Storage Model

Primary hosted storage lives in Supabase:

- `public.agent_memory_items`
  - durable memory items (`namespace`, `title`, `content`, `tags`, `visibility`, `metadata`)
  - owner-scoped by user or OAuth client identity
  - includes vector-capable schema fields (`embedding`, `embedding_model`)
- `public.agent_context_edges`
  - graph triples (`subject`, `predicate`, `object`) linked to memory item ids when available
  - owner + namespace scoped
- `public.agent_memory_search_v1(...)`
  - RPC used by `memory.search`

## Query Model (Current Runtime)

### `memory.search`

- Tool: `memory.search` via `POST /api/mcp`
- Runtime behavior: text-ranked retrieval + recency tie-break
- Request shape: `namespace`, `query`, optional `since`, optional `limit`
- Response shape: `structuredContent.items` (array), no `total` field

Important implementation note:

- The search RPC supports vector similarity when `in_query_embedding` is supplied.
- Current worker path calls RPC with `in_query_embedding: null`, so production MCP search is text-ranked today.

### `graph.edge.search`

- Tool: `graph.edge.search` via `POST /api/mcp`
- Returns context edges for owner+namespace, filterable by term/relation and bounded by limit.

## Encryption and Queryability

If a client stores ciphertext in `content`, the hosted runtime cannot semantically understand plaintext it never receives.  
In that mode, retrieval quality depends on any plaintext metadata you choose to include (for example: `title`, `tags`, selected metadata keys).

## Minimal Query Examples

```bash
# Memory retrieval (text-ranked)
curl -s https://mnemolog.com/api/mcp \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $MNA_TOKEN" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"tools/call",
    "params":{
      "name":"memory.search",
      "arguments":{"namespace":"project:mnemolog","query":"rate limit", "limit":10}
    }
  }' | jq .
```

```bash
# Graph retrieval
curl -s https://mnemolog.com/api/mcp \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $MNA_TOKEN" \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/call",
    "params":{
      "name":"graph.edge.search",
      "arguments":{"namespace":"project:mnemolog","term":"pricing","limit":20}
    }
  }' | jq .
```