Metadata-Version: 2.4
Name: synapt
Version: 0.14.0
Summary: Persistent conversational memory for AI coding assistants
Author: Layne Penney
License-Expression: MIT
Project-URL: Homepage, https://synapt.dev
Project-URL: Repository, https://github.com/synapt-dev/recall
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]>=1.0
Requires-Dist: sentence-transformers>=2.0
Requires-Dist: mlx-lm>=0.10; sys_platform == "darwin" and platform_machine == "arm64"
Requires-Dist: anthropic>=0.70
Requires-Dist: openai-agents>=0.10
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.77.0; extra == "anthropic"
Provides-Extra: openai
Requires-Dist: openai-agents>=0.10.0; extra == "openai"
Provides-Extra: google-adk
Requires-Dist: google-adk>=1.0.0; extra == "google-adk"
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2; extra == "langchain"
Provides-Extra: crewai
Requires-Dist: crewai>=1.4.0; extra == "crewai"
Provides-Extra: all-integrations
Requires-Dist: anthropic>=0.77.0; extra == "all-integrations"
Requires-Dist: openai-agents>=0.10.0; extra == "all-integrations"
Requires-Dist: google-adk>=1.0.0; extra == "all-integrations"
Requires-Dist: langchain-core>=0.2; extra == "all-integrations"
Requires-Dist: crewai>=1.4.0; extra == "all-integrations"
Provides-Extra: hf
Requires-Dist: huggingface_hub>=0.20; extra == "hf"
Provides-Extra: onnx
Requires-Dist: onnxruntime>=1.16; extra == "onnx"
Requires-Dist: optimum[onnxruntime]>=1.16; extra == "onnx"
Provides-Extra: transformers
Requires-Dist: transformers>=4.30; extra == "transformers"
Requires-Dist: peft>=0.7; extra == "transformers"
Provides-Extra: x
Requires-Dist: tweepy>=4.14; extra == "x"
Provides-Extra: dashboard
Requires-Dist: fastapi>=0.100; extra == "dashboard"
Requires-Dist: uvicorn[standard]>=0.20; extra == "dashboard"
Requires-Dist: sse-starlette>=1.0; extra == "dashboard"
Requires-Dist: markdown>=3.4; extra == "dashboard"
Provides-Extra: dev
Requires-Dist: watchfiles>=0.20; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: numpy; extra == "test"
Requires-Dist: pytest-benchmark>=4.0; extra == "test"
Requires-Dist: fastapi>=0.100; extra == "test"
Requires-Dist: uvicorn[standard]>=0.20; extra == "test"
Requires-Dist: sse-starlette>=1.0; extra == "test"
Requires-Dist: markdown>=3.4; extra == "test"
Dynamic: license-file

<!-- mcp-name: io.github.synapt-dev/recall -->
<p align="center">
  <img src="assets/banner.png" alt="Synapt" width="100%">
</p>

<p align="center">
  <a href="https://pypi.org/project/synapt/"><img src="https://img.shields.io/pypi/v/synapt?color=7c5cbf" alt="PyPI"></a>
  <a href="https://pypi.org/project/synapt/"><img src="https://img.shields.io/pypi/pyversions/synapt?color=00e5cc" alt="Python"></a>
  <a href="https://github.com/synapt-dev/recall/blob/main/LICENSE"><img src="https://img.shields.io/github/license/synapt-dev/recall" alt="License"></a>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Anthropic_Memory-ready-D97706?logo=anthropic&logoColor=white" alt="Anthropic Memory Tool">
  <img src="https://img.shields.io/badge/OpenAI_Agents-ready-412991?logo=openai&logoColor=white" alt="OpenAI Agents">
  <img src="https://img.shields.io/badge/Google_ADK-ready-4285F4?logo=google&logoColor=white" alt="Google ADK">
  <img src="https://img.shields.io/badge/LangChain-ready-1C3C3C?logo=langchain&logoColor=white" alt="LangChain">
  <img src="https://img.shields.io/badge/CrewAI-ready-FF6B35?logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0id2hpdGUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PGNpcmNsZSBjeD0iOCIgY3k9IjgiIHI9IjYiLz48L3N2Zz4=&logoColor=white" alt="CrewAI">
  <img src="https://img.shields.io/badge/Claude_Code-ready-D97706?logo=anthropic&logoColor=white" alt="Claude Code">
  <img src="https://img.shields.io/badge/Codex_CLI-ready-412991?logo=openai&logoColor=white" alt="Codex CLI">
</p>

<p align="center">
  Memory and coordination infrastructure for AI coding teams.<br>
  Search past sessions, preserve decisions, coordinate agents, and ship from one persistent system of record.
</p>

<p align="center">
  <a href="https://synapt.dev">Website</a> &middot;
  <a href="https://synapt.dev/guide.html">Guide</a> &middot;
  <a href="https://synapt.dev/blog/">Blog</a> &middot;
  <a href="https://x.com/synapt_dev">@synapt_dev</a>
</p>

---

**synapt** gives Claude Code, Codex CLI, OpenCode, and other MCP-compatible assistants persistent operational memory.

It closes the gap between a one-shot assistant and a real working team:
- recall prior sessions, file history, decisions, and unresolved work
- preserve context in journals, reminders, and knowledge nodes
- coordinate multiple agents through shared channels, directives, and task claims
- scale from solo recall on a laptop to multi-agent operational memory

Agent skill files for repository-native use live in:
- `.codex/skills/synapt/SKILL.md`
- `.claude/skills/synapt/SKILL.md`

## Three-command quickstart

For the default Claude Code path:

```bash
pip install synapt
claude mcp add synapt -- synapt server
synapt init
```

That gives you:
- a project-local `.synapt/` memory store
- indexed Claude Code and Codex transcripts
- Claude hooks for automatic archive/build flow
- the published Codex `dev-loop` skill installed into `${CODEX_HOME:-~/.codex}/skills/dev-loop/`

## Platform setup

### Claude Code

Recommended:

```bash
pip install synapt
claude mcp add synapt -- synapt server
synapt init
```

### Codex CLI

Install:

```bash
pip install synapt
```

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.synapt]
command = "synapt"
args = ["server"]
```

Then initialize the project:

```bash
synapt init
```

### OpenCode

Add to `~/.config/opencode/opencode.json`:

```json
{
  "mcp": {
    "synapt": {
      "type": "local",
      "command": ["synapt", "server"],
      "enabled": true
    }
  }
}
```

Then run:

```bash
synapt init
```

### Manual MCP config

If your client accepts stdio MCP definitions directly, use:

```json
{
  "mcpServers": {
    "synapt": {
      "type": "stdio",
      "command": "synapt",
      "args": ["server"]
    }
  }
}
```

## Framework integrations

synapt plugs into popular agent frameworks as a drop-in memory backend. Each adapter wraps recall's search and save API for the framework's native session interface.

Install all integration dependencies at once:

```bash
pip install synapt[all-integrations]
```

Or install only the ones you need:

```bash
pip install synapt[anthropic]    # Anthropic Memory Tool
pip install synapt[openai]       # OpenAI Agents SDK
pip install synapt[google-adk]   # Google ADK
pip install synapt[langchain]    # LangChain
pip install synapt[crewai]       # CrewAI
```

### Anthropic Memory Tool

`SynaptMemoryTool` is a drop-in replacement for `BetaAbstractMemoryTool`. It presents recall's knowledge graph as a virtual filesystem that Claude can view, create, edit, and search. All writes are persisted as durable recall knowledge nodes.

```bash
pip install synapt[anthropic]
```

**Before** (default memory, no cross-session persistence):

```python
from anthropic import Anthropic

client = Anthropic()
response = client.beta.messages.run_tools(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Remember that we use blue-green deploys"}],
    tools=[{"type": "memory_20250818", "name": "memory"}],
).until_done()
```

**After** (recall-backed memory with hybrid search):

```python
from anthropic import Anthropic
from synapt.integrations.anthropic import SynaptMemoryTool

client = Anthropic()
memory = SynaptMemoryTool()

response = client.beta.messages.run_tools(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Remember that we use blue-green deploys"}],
    tools=[memory],
).until_done()
```

An async variant (`SynaptAsyncMemoryTool`) is available for `AsyncAnthropic` clients.

### OpenAI Agents SDK

`SynaptSession` is a session persistence adapter for the Agents SDK `Session` protocol. Items are stored in SQLite with non-blocking async DB access. Recall search and memory context are available as convenience methods.

```bash
pip install synapt[openai]
```

**Before** (default SQLiteSession, no cross-session search):

```python
from agents import Agent, Runner
from agents.memory import SQLiteSession

session = SQLiteSession(session_id="user-123", db_path="sessions.db")
runner = Runner(agent=agent, session=session)
```

**After** (recall-backed session with memory context):

```python
from agents import Agent, Runner
from synapt.integrations.openai_agents import SynaptSession

session = SynaptSession(session_id="user-123")
runner = Runner(agent=agent, session=session)

# Retrieve recall context for agent prompts
context = session.get_memory_context("deployment strategy")

# Persist durable knowledge
session.save_to_recall("Always use UTC timestamps", category="convention")
```

### Google ADK

`SynaptMemoryService` is a drop-in replacement for ADK's `InMemoryMemoryService`. Session events are indexed in recall's knowledge graph; `search_memory` uses hybrid retrieval instead of keyword matching.

```bash
pip install synapt[google-adk]
```

**Before** (default in-memory, keyword-only search):

```python
from google.adk.agents import LlmAgent
from google.adk.memory import InMemoryMemoryService

memory = InMemoryMemoryService()
agent = LlmAgent(model="gemini-2.5-flash", name="my_agent", memory_service=memory)
```

**After** (recall-backed, hybrid search):

```python
from google.adk.agents import LlmAgent
from synapt.integrations.google_adk import SynaptMemoryService

memory = SynaptMemoryService()
agent = LlmAgent(model="gemini-2.5-flash", name="my_agent", memory_service=memory)
```

### LangChain

`SynaptChatMessageHistory` implements LangChain's `BaseChatMessageHistory`. Messages are stored in SQLite with WAL mode; recall search and knowledge persistence are one method call away.

```bash
pip install synapt[langchain]
```

```python
from langchain_core.messages import HumanMessage
from synapt.integrations.langchain import SynaptChatMessageHistory

history = SynaptChatMessageHistory(session_id="user-123")
history.add_messages([HumanMessage(content="hello")])
print(history.messages)

# Semantic search across all indexed sessions
results = history.search("deployment config")

# Persist a decision as a durable knowledge node
history.save_to_recall("Always use UTC timestamps", category="convention")
```

Works with `RunnableWithMessageHistory`, `ConversationChain`, and any LangChain component that accepts a `BaseChatMessageHistory`.

### CrewAI

`SynaptMemory` provides long-term memory storage for CrewAI crews, backed by recall's hybrid search.

```bash
pip install synapt[crewai]
```

```python
from synapt.integrations.crewai import SynaptMemory

memory = SynaptMemory()
crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task],
    memory=memory,
)
crew.kickoff()
```

### Google ADK

`SynaptMemoryService` implements ADK's `BaseMemoryService` with tenant-scoped search and persistence.

```bash
pip install synapt[google-adk]
```

```python
from synapt.integrations.google_adk import SynaptMemoryService

memory = SynaptMemoryService()
# search_memory scopes results by app_name and user_id
# add_memory persists with tenant tags for isolation
```

### Claude Code (native memory backend)

Replace Claude Code's built-in memory with recall-backed persistent memory in one line:

```python
from synapt.integrations.anthropic import SynaptMemoryTool

# Drop-in replacement for BetaLocalFilesystemMemoryTool
tool = SynaptMemoryTool()
```

Every `create`, `view`, `str_replace`, and `search` call now goes through recall: files are persisted, content is enriched, and search returns semantically relevant results across sessions. No configuration needed; `pip install synapt` includes everything.

For MCP-based recall (search, journals, channels, 20+ tools):

```bash
pip install synapt
claude mcp add synapt -- synapt server
synapt init
```

`synapt init` installs session hooks for automatic transcript archiving.

### Codex CLI

Install synapt and register the MCP server:

```bash
pip install synapt
```

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.synapt]
command = "synapt"
args = ["server"]
```

Then initialize the project:

```bash
synapt init
```

`synapt init` installs the `dev-loop` skill automatically, giving Codex recall search, channel coordination, and journal access.

## What `synapt init` does

Run from a project root:

```bash
synapt init
```

It will:
1. archive project-relevant Claude Code and Codex transcripts
2. build the `.synapt/recall/index/recall.db` search index
3. register the Synapt MCP server in Claude Code when the `claude` CLI is available
4. install Claude hooks for `SessionStart`, `SessionEnd`, and `PreCompact`
5. deploy the packaged Codex `dev-loop` skill
6. add `.synapt/` to `.gitignore`

`synapt recall setup` remains available as the explicit recall-scoped equivalent.

## Product tiers

synapt is one memory system with a clear adoption ladder:

### 1. Solo recall

Search prior sessions, file history, timelines, and journals on one machine.

```bash
synapt recall search "how did we fix auth"
synapt recall files "src/auth.py"
synapt recall timeline
```

### 2. Multi-agent memory

Add channels, directives, reminders, and task claims for coordinated execution across worktrees and agents.

```python
recall_channel(action="join", channel="dev", name="Atlas")
recall_channel(action="intent", channel="dev", message="reviewing PR #403")
recall_channel(action="claim", channel="dev", message="m_abc123")
```

### 3. Dashboard

Expose the same shared operational memory in a browser-facing mission-control surface.

### 4. Spawn / orchestration

Use synapt as the memory and coordination substrate beneath higher-level agent orchestration.

## Core features

- **Hybrid search**: BM25 + embeddings + reciprocal rank fusion + reranking
- **File-aware recall**: find where a file, bug, issue, or decision was handled before
- **Journal + knowledge**: durable summaries, extracted facts, contradictions, and timeline arcs
- **Agent channels**: shared append-only coordination across sessions and worktrees
- **Cross-client memory**: Claude Code and Codex transcripts converge into one searchable system
- **Portable archive**: export/import `.synapt-archive` state between machines
- **Plugin system**: extend MCP tools and CLI commands through Python entry points

## Benchmarks

### LOCOMO

LOCOMO evaluates long conversational memory over 10 conversations and 1540 QA pairs.

All systems use gpt-4o-mini as the shared generation + judge backbone for fair comparison. Competitor data comes from the [Engram paper](https://arxiv.org/abs/2511.12960) and [Mem0 paper](https://arxiv.org/abs/2504.19413).

| System | **Overall** | Multi-Hop | Temporal | Infra |
|--------|-------------|-----------|----------|-------|
| Engram | 77.55 ± 0.13 | — | — | cloud (BM25+ColBERT+KG) |
| Memobase | 75.78 | 46.88 | **85.05** | cloud |
| memOS | 72.99 ± 0.14 | — | — | cloud |
| Full-Context | 72.90 | — | — | upper bound |
| **synapt (audited)** | **72.4** | **70.92** | 59.19 | Ministral 8B cloud enrich |
| **synapt local-first** | **72.4** | 67.02 | 61.06 | **local 3B on M2 Air** |
| Mem0 | 64.73 ± 0.17 | 51.15 | 55.51 | cloud GPT-4 |
| Zep | 42.29 ± 0.18 | — | — | cloud |

What matters for the pitch:
- synapt is competitive with the best published systems
- the local-first path remains strong on commodity hardware
- the system is explicit about benchmark methodology, retrieval tradeoffs, and judge-model drift
- the 72.4 LOCOMO score is the audited, reproducible number to cite

Sources:
- [LOCOMO](https://snap-research.github.io/locomo/)
- [Mem0 paper](https://arxiv.org/abs/2504.19413)
- [Engram paper](https://arxiv.org/abs/2511.12960)
- [Memobase benchmark](https://github.com/memodb-io/memobase/blob/main/docs/experiments/locomo-benchmark/README.md)

### CodeMemo

CodeMemo evaluates coding-memory tasks across factual recall, debugging context, architecture, temporal ordering, conventions, and cross-session continuity.

| System | Overall |
|--------|---------|
| **synapt v0.6.2** | **90.51** |
| Mem0 | 76.00 |

Source:
- [CodeMemo benchmark](evaluation/codememo/README.md)

## Security and compliance

synapt is built for teams that care where memory lives and how it is inspected.

- **Local-first by default**: transcripts, channels, journals, and indexes live on disk under `.synapt/`
- **No mandatory cloud memory backend**: core recall works locally
- **Inspectable storage**: JSONL transcripts plus SQLite/FTS5 state
- **Portable backup path**: export/import via `.synapt-archive`
- **Optional remote behavior is explicit**: sync and plugin integrations are opt-in

For disclosure and reporting policy, see [SECURITY.md](SECURITY.md).

## Example workflows

Search a prior fix:

```bash
synapt recall search "why did we disable snippets in retrieval-only mode"
```

Find a file’s prior context:

```bash
synapt recall files "src/synapt/recall/channel.py"
```

Run Codex on a timed review loop:

```bash
./scripts/codex-loop.sh \
  --interval 60 \
  --prompt "check #dev, review fresh PRs, or pick up the next unowned task. Post what you're doing in #dev." \
  -- --full-auto
```

## Why teams adopt it

Without memory, every new assistant session starts as a stranger.

With synapt, teams can:
- recover prior decisions instead of re-deriving them
- hand off work without losing context
- coordinate multiple agents without duplicating effort
- keep operational memory local, inspectable, and portable

That is the difference between an assistant demo and an operational system.
