Agent Memory

Synapses gives agents episodic memory that persists across sessions. Agents can record decisions, failures, and patterns, then recall them later using full-text search or semantic matching. Memory entries anchor to graph nodes, so Synapses can detect when referenced code has changed (staleness).

Recording Episodes

Use memory(action="save") to store an episode:

{
  "tool": "memory",
    "action": "save",
  "arguments": {
    "episode_type": "decision",
    "content": "Chose connection pooling over per-request connections for the webhook client. Pooling reduces latency by ~40ms per call based on benchmarks.",
    "tags": ["webhook", "performance", "architecture"],
    "entities": ["internal/webhook/client.go:NewClient"]
  }
}

Episode Types

Anchoring to Graph Nodes

The entities field links the episode to specific nodes in the code graph:

{
  "entities": [
    "internal/webhook/client.go:NewClient",
    "internal/webhook/client.go:WebhookClient"
  ]
}

When those entities change (file modified, function signature updated), Synapses marks the episode as potentially stale. This prevents agents from acting on outdated information.

Recalling Episodes

Full-Text Search

{
  "tool": "memory",
    "action": "search",
  "arguments": {
    "query": "webhook connection pool",
    "limit": 5
  }
}

Uses FTS5 for fast full-text matching across episode content and tags.

Filtered Recall

{
  "tool": "memory",
    "action": "search",
  "arguments": {
    "query": "performance",
    "episode_type": "decision",
    "tags": ["architecture"]
  }
}

Combine text search with type and tag filters.

Semantic Search

When the query does not match exact keywords, Synapses falls back to semantic similarity matching. This finds episodes that are conceptually related even if they use different terminology.

{
  "tool": "memory",
    "action": "search",
  "arguments": {
    "query": "how do we handle HTTP timeouts"
  }
}
// Finds episodes about connection pooling, retry logic, deadline propagation

Getting All Episodes

{
  "tool": "get_episodes",
  "arguments": {
    "entity": "internal/webhook/client.go:NewClient"
  }
}

Returns all episodes anchored to a specific entity. Useful when you are about to modify code and want to know the full history of decisions and failures related to it.

Staleness Detection

When an entity referenced by an episode has changed since the episode was recorded, the episode is flagged:

{
  "stale": true,
  "stale_reason": "Entity internal/webhook/client.go:NewClient modified since episode was recorded",
  "recorded_at": "2026-03-15T10:30:00Z",
  "entity_modified_at": "2026-03-20T14:22:00Z"
}

Agents should treat stale episodes with caution — the decision or pattern may no longer apply.

Failure-Point Resumption

Failure episodes enable intelligent resumption. When an agent encounters a problem and records it:

{
  "tool": "memory",
    "action": "save",
  "arguments": {
    "episode_type": "failure",
    "content": "Retry logic causes duplicate webhook deliveries when the upstream returns 503 but processes the request. Need idempotency keys.",
    "tags": ["webhook", "retry", "idempotency"],
    "entities": ["internal/webhook/sender.go:SendWithRetry"]
  }
}

A future session can recall this failure before attempting the same area:

{
  "tool": "memory",
    "action": "search",
  "arguments": {
    "query": "webhook retry",
    "episode_type": "failure"
  }
}
// Returns the duplicate delivery failure episode
// Agent knows to implement idempotency keys before retrying

Memory in Context Responses

When you call get_context(mode="intent") or get_context, relevant episodes are included automatically in the response. You do not need to call recall separately — Synapses matches episodes to the entities in your context packet.

Best Practices

• Record decisions with rationale. Future agents (or future you) will want to know why, not just what.
• Record failures immediately. The details are freshest right after encountering the problem.
• Use specific entity anchors. Anchoring to internal/auth/jwt.go:ValidateToken is better than no anchor — it enables staleness detection.
• Tag consistently. Use lowercase, short tags. Check existing tags via memory(action="search") before inventing new ones.
• Check for stale episodes. Before acting on a recalled decision, verify the referenced code has not changed significantly.