Skip to main content

​
Install

pip install synap-claude-agent

​
What’s included

ExportLanguagePurpose
create_synap_hooksPython + TSReturns a hooks dict for automatic context injection and turn recording
create_synap_mcp_serverPython + TSReturns an MCP server exposing synap_search and synap_remember as tools
build_synap_toolsTypeScriptRaw tool definitions for manual composition

​
Hooks — automatic memory

Use hooks for zero-friction memory: Synap injects context before each turn and records the response after — no tool calls needed from the model. 
import asyncio
from anthropic.claude_agent_sdk import query, ClaudeAgentOptions
from synap_claude_agent import create_synap_hooks

hooks = create_synap_hooks(
    sdk=sdk,
    user_id="alice",
    customer_id="acme",   # optional
    conversation_id="conv-001",  # optional; auto-generated if omitted
)

async def main():
    async for message in query(
        prompt="What did I tell you about my trial account?",
        options=ClaudeAgentOptions(hooks=hooks),
    ):
        print(message)

asyncio.run(main())

​
How hooks work

  1. before_query — fetches Synap context and prepends it as a system message
  2. after_turn — ingests the completed user + assistant turn into Synap
Failures on step 1 degrade gracefully (empty context, error logged). Failures on step 2 surface explicitly.

​
MCP server — explicit memory tools

Use the MCP server when you want the model to decide when to search or store memories. The server exposes two tools:
  • synap_search — search memories by query
  • synap_remember — store a new memory
from anthropic.claude_agent_sdk import query, ClaudeAgentOptions
from synap_claude_agent import create_synap_hooks, create_synap_mcp_server

hooks = create_synap_hooks(sdk=sdk, user_id="alice")
mcp_server = create_synap_mcp_server(sdk=sdk, user_id="alice")

async for message in query(
    prompt="Search your memory for anything about my project deadlines.",
    options=ClaudeAgentOptions(
        hooks=hooks,
        mcp_servers={"synap": mcp_server},
    ),
):
    print(message)

​
Hooks vs. MCP server

HooksMCP server
Context injectionAutomatic, every turnOn-demand via tool call
Memory storageAutomatic, every turnOn-demand via tool call
Model awarenessModel doesn’t see the toolsModel can decide when to search/store
Best forProduction agents where memory is always neededResearch agents where explicit memory control matters
Use both together for maximum coverage: hooks handle automatic ingestion, MCP tools let the model query memory explicitly when needed.

​
TypeScript: buildSynapTools

For manual composition without the full MCP server: 
import { buildSynapTools } from "@maximem/synap-claude-agent";

const tools = buildSynapTools({ sdk, userId: "alice", customerId: "acme" });
// tools = [synapSearchTool, synapRememberTool] — raw Anthropic tool definitions

​
Next steps

Vercel AI SDK

Middleware for any Vercel AI SDK model.

Mastra

SynapMemory for the Mastra ADK.