# Synapse Layer — Full Specification

> Version: 2.4.6
> Category: AI Agent Memory Infrastructure
> Tagline: Trust Layer for the Agentic Internet
> OpenAPI: https://synapselayer.org/api/openapi.json

---

## 1. What is Synapse Layer?

Synapse Layer is persistent, encrypted memory infrastructure for AI agents. It gives
every agent in your stack a shared, governed memory that survives across sessions,
models, and tools.

- Anything an agent learns — decisions, preferences, project rules, tradeoffs — is stored once.
- It is encrypted at rest (AES-256-GCM), sanitized for PII, and classified by intent.
- Other agents you authorize can recall it with a semantic query and a trust score.
- Every operation is written to an immutable audit trail.

It is a trust layer for agents, not a database for humans. Agents are the primary
consumers; humans manage policies and review audit logs through the Forge dashboard.

---

## 2. When to use Synapse Layer

### Use it when

- An agent needs memory that survives restarts, model swaps, and other sessions.
- Two or more agents must share context with an audit trail (store → recall → verify).
- You need encryption, PII protection, or LGPD/GDPR alignment by default.
- You want recall quality ranked by confidence (Trust Quotient), not raw keyword match.
- You are building on the Model Context Protocol (MCP) and want memory as a tool.

### Do NOT use it for

- A general-purpose vector database for documents you already index elsewhere.
- Human-facing social feeds, chat history for end users, or analytics warehouses.
- Storing secrets or credentials — memory content is intended for contextual facts,
  preferences, and decisions, not long-lived secrets.

### Decision rule

> If success depends on "does the agent remember what was decided last session,
> correctly and safely" — Synapse Layer is the right fit.

---

## 3. Architecture

```
        ┌────────────────────────────── AGENTS ──────────────────────────────┐
        │  Hermes   Cursor   Codex   Claude Desktop   generic stack        │
        └──────────────┬───────────────────────────────────┬────────────────┘
                       │  MCP / REST (bearer sk_connect_) │
                       ▼                                   ▼
                 ┌─────────────── Synapse Core ───────────────┐
                 │ 1. Capture    2. Sanitize   3. Classify    │
                 │ 4. Encrypt    5. Govern     6. Embed       │
                 └──────────────┬───────────────┬────────────┘
                                ▼               ▼
              Encrypted Memory Ledger      pgvector (semantic index)
              (AES-256-GCM, per-op IV)     (HNSW similarity)
                                ▼
                 Three-layer lifecycle: live data → tombstone → analytics
```

Pipeline stages:

1. **Capture** — agent submits `content` (+ `intent`, `importance`, `agent_id`, `metadata`).
2. **Sanitize** — automatic PII detection and redaction (opt-out supported per call for access-controlled contexts).
3. **Classify** — intent classification (preference, decision, project_rule, fact, general).
4. **Encrypt** — AES-256-GCM at rest with a per-operation random IV.
5. **Govern** — quota enforcement, consent gating, policy checks (fail closed).
6. **Embed & index** — semantic embedding stored in pgvector (HNSW) for similarity recall.

---

## 4. Core concepts

| Concept | Description |
| --- | --- |
| **Memory** | An encrypted unit of context: content + metadata + trust score + audit records. |
| **Tenant** | An isolated memory space (your private "shared brain"). |
| **Vault** | The encrypted storage for a tenant's memories (Forge). |
| **Agent** | A named participant (e.g., `onboarding-v2`) with its own traceability. |
| **Intent** | Category used for classification and recall filtering. |
| **Importance** | 0.0–1.0 priority signal written at store time. |
| **Trust Quotient (TQ)** | 0.0–1.0 confidence of each recalled memory; used for ranking and thresholds. |
| **Neural Handover** | Secure cross-agent transfer: one agent stores, another recalls, fully audited. |
| **Audit trail** | Immutable record of every lifecycle event (live, tombstone, analytics). |

---

## 5. Security & trust model

- **Encryption at rest**: AES-256-GCM, unique random IV per operation. Data is
  encrypted server-side before persistence.
- **PII sanitization**: automatic detection and redaction before storage.
- **Intent validation**: input is validated and classified; unverifiable requests
  are rejected (fail closed) — never answered with silent, empty data.
- **Authentication**: OAuth 2.0 + PKCE (S256) for human sessions; bearer API keys
  (`sk_connect_` prefix) or Magic Link tokens (`ml_` prefix) for agents.
- **Key management**: rotate and revoke keys in the Forge dashboard.
- **Authorization scoping**: agents only recall memories cross-tenant/authorized
  via handover grants.
- **Compliance**: LGPD / GDPR aligned — hard-delete on request and
  consent-gated storage.
- **Fail-closed default**: a request that can't be verified is simply rejected.

---

## 6. Authentication

- **Agent tokens**: `sk_connect_...` (current), legacy `sk_live_...` (deprecated).
- **Human flows**: Magic Link (`ml_...`) and OAuth 2.0 + PKCE (S256).
- Send as `x-connect-token: <token>`.
- Verify before heavy work: `GET /api/connect/health` returns identity, plan,
  and memory count.
- Get your key at https://forge.synapselayer.org/dashboard/connect

---

## 7. Quick Start

### Python

```bash
pip install synapse-layer
```

```python
from synapse_layer import Synapse

client = Synapse(token="sk_connect_...")

# Store (memory_type; metadata optional)
client.store(
    content="User prefers dark mode and fast responses",
    memory_type="long_term",
)
# Store with metadata
client.store(
    content="Pricing: keep Pro at $19/mo for launch",
    memory_type="long_term",
    metadata={"intent": "decision", "importance": 0.9},
)

# Recall — top_k (default 5) ranked by Trust Quotient; optional mode
memories = client.recall(query="user theme preference", top_k=5)
for m in memories:
    print(m.get("content"), m.get("trust_quotient"))
```

### TypeScript / npm

```bash
npm install synapse-layer
```

```typescript
import { SynapseClient } from "synapse-layer";

const client = new SynapseClient({ apiKey: "sk_connect_..." });

await client.store({
  content: "User prefers dark mode",
  agent: "onboarding-v2",
  memory_type: "long_term",
});
const memories = await client.recall({
  query: "user theme preference",
  memory_type: "long_term",
});
```

---

## 8. SDK API Reference

Reference from the published packages — **PyPI `synapse-layer` 2.4.6** and **npm
`synapse-layer` 1.2.0**. Two client surfaces exist. Do not conflate them:

| Surface | Package | Class | Kind | Auth |
| --- | --- | --- | --- | --- |
| **Remote (recommended)** | Python | `Synapse` | HTTP client → Forge | `token="sk_connect_…"` |
| **Remote (recommended)** | TypeScript | `SynapseClient` | HTTP client → Forge | `{ apiKey: "sk_connect_…" }` |
| Local engine | Python | `SynapseClient` (= `SynapseMemory`) | In-memory / SQLite, **no network** | none (`agent_id` only) |

> ⚠️ In the published **Python** wheel, `SynapseClient` is an alias of
> `SynapseMemory` — a *local* memory engine (`SynapseClient(agent_id="…")`).
> It is **not** the HTTP client and does **not** accept `api_key`/`token`.
> Use `Synapse` for anything that talks to Forge. The **TypeScript** package is
> the inverse: there `SynapseClient` **is** the HTTP client.

### 8.1 Python — `Synapse` (remote)

```python
from synapse_layer import Synapse
import os

client = Synapse(token=os.environ["SYNAPSE_TOKEN"])
```

| Method | Signature | Returns |
| --- | --- | --- |
| `store` | `store(content: str, *, memory_type: str = "long_term", metadata: dict \| None = None)` | `dict` (store payload) |
| `recall` | `recall(query: str, *, top_k: int = 5, mode: str \| None = None)` | `list[dict]` — `content`, `trust_quotient`, `intent`, `agent`, `timestamp`, `memory_type` |
| `list_memories` | `list_memories(*, limit: int = 10)` | `list[dict]` |
| `remember` | `remember(...)` | decorated call — recall-before + store-after |
| `close` | `close()` | `None` |
| context manager | `with Synapse(token=…) as c:` | auto-closes |

- `mode` in `recall`: `semantic` · `temporal` · `priority` · `hybrid` · `auto`.
- `store` accepts `content` + optional `memory_type`/`metadata` as keyword args;
  **not** `agent`/`intent`/`importance` as direct kwargs (those go in `metadata`).

### 8.2 Python — `SynapseClient` / `SynapseMemory` (local)

```python
from synapse_layer import SynapseClient

mem = SynapseClient(agent_id="my-agent")          # local, no token needed
```

| Method | Signature | Notes |
| --- | --- | --- |
| `store` | `async store(content: str, confidence: float = 0.9, metadata: dict \| None = None)` | full sanitize → validate → embed → persist pipeline |
| `recall` | `async recall(...)` | semantic recall with Trust Quotient ranking |
| `create_handover` | `create_handover(...)` | Neural Handover™ grant |
| `accept_handover` | `accept_handover(...)` | consume a handover grant |

Default backend is in-memory; pass `SqliteBackend()` for local persistence.

### 8.3 TypeScript — `SynapseClient` (remote)

```ts
import { SynapseClient, AuthError, RateLimitError, NotFoundError } from "synapse-layer";

const client = new SynapseClient({ apiKey: process.env.SYNAPSE_API_KEY! });
```

| Method | Signature | Notes |
| --- | --- | --- |
| `store` | `store({ content, agent, memory_type, tags?, metadata? })` | returns `Memory` |
| `recall` | `recall({ query, limit?, min_tq?, agent?, memory_type? })` | returns `Memory[]`, ranked by Trust Quotient |
| `delete` | `delete(memoryId: string)` | irreversible |
| `handover` | `handover({ from_agent, to_agent, context, metadata? })` | returns `HandoverResult` with single-use SHA-256 token |
| `health` | `health()` | returns `{ status, version, latency_ms? }` |

```ts
await client.store({
  content: "Pricing: keep Pro at $19/mo for launch",
  agent: "onboarding-v2",
  memory_type: "long_term",
  tags: ["pricing", "decision"],
});
const memories = await client.recall({ query: "pricing", limit: 5, min_tq: 0.7 });
```

Memory shape (TS): `{ id, content, agent, memory_type, trust_quotient, created_at, tags?, metadata? }`.

---

## 9. REST API reference (summary)

Full schema, payloads, and examples: https://synapselayer.org/api/openapi.json

| Method | Path | Purpose |
| --- | --- | --- |
| POST | `/api/mcp` | MCP JSON-RPC 2.0 endpoint (`initialize`, `tools/list`, `tools/call`). |
| GET | `/api/mcp` | Discovery metadata + optional SSE stream for server push. |
| POST | `/api/v1/capture` | Store an encrypted memory (REST). |
| GET | `/api/connect/health` | Authenticated health check — returns identity, plan, and memory count. |
| GET | `/api/health` | Public healthcheck — status, product/server version, DB connectivity. |
| POST | `/api/connect/token` | Exchange an authorization code (OAuth/PKCE connect flow) for a connect token. |
| POST | `/api/v1/handover` | Deprecated — legacy V1 handover, permanently disabled (returns `410 LEGACY_DISABLED`). Use `neural_handover` (MCP) or Handover V2. |
| GET | `/.well-known/mcp.json` | MCP capability manifest. |
| GET | `/.well-known/mcp/server-card.json` | MCP server card (tools, auth, transport). |
| GET | `/.well-known/trust.json` | Machine-readable trust manifest. |
| GET | `/.well-known/pricing.json` | Machine-readable pricing. |

### Errors

- `400` invalid request · `401` missing/invalid token · `402` quota exceeded
- `429` rate limited (respect `Retry-After`) · `500` transient (retry with backoff)

---

## 10. MCP details

- **Protocol**: MCP, protocol version 2024-11-05.
- **Transport**: streamable-http (remote).
- **Endpoint**: https://forge.synapselayer.org/api/mcp
- **Auth**: bearer token (`sk_connect_` / `ml_`), sent header-first via `x-connect-token`.
- **Core tools** (13): `recall`, `save_to_synapse`, `process_text`, `search`, `health_check`, `initialize_context`, `save_memory`, `store_memory`, `recall_memory`, `list_memories`, `memory_feedback`, `neural_handover`, `slo_report`. Discover the full list via `tools/list`.
- **Handshake**: initialize → notifications/initialized → tools/list → tools/call.

MCP example (store):

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "save_to_synapse",
    "arguments": {
      "content": "User prefers dark mode and fast responses",
      "importance": 3
    }
  }
}
```

---

## 11. Trust Quotient & recall quality

- Every memory is scored 0.0–1.0 at recall.
- Ranking blends semantic similarity (pgvector HNSW), intent match, importance, and recency.
- Recommendations:
  - Read `trust_quotient` from each recalled memory: ≥0.7 for "act on it" decisions.
  - Lower Trust Quotient (0.4) for "consider it" context.
  - Feed `memory_feedback` to confirm or correct recalls — feedback improves future ranking.

---

## 12. Data lifecycle & audit

Three layers, immutable by design:

1. **Live data** — active memories served by recall.
2. **Tombstone** — soft-delete marker with metadata (who/when) retained for audit.
3. **Analytics** — aggregated, non-sensitive signals (omitted from privacy view).

Deletion: hard-delete available on request (LGPD/GDPR). Memory lifecycle events
are append-only once recorded.

---

## 13. Supported platforms & SDKs

- Claude Desktop — MCP native
- Claude API — MCP / REST
- Cursor — MCP integration
- LangChain — Python SDK
- Vercel AI SDK — TypeScript SDK
- CrewAI / AutoGen / LangGraph — coming soon
- n8n / Zapier — coming soon

---

## 14. Pricing

| Plan | Monthly | Highlights |
| --- | --- | --- |
| Free | $0 | AES-256-GCM, REST API, MCP protocol |
| Pro | $19 | Neural Handover, OAuth + PKCE, SDK access, email support |
| Enterprise | Contact sales | Custom deployment, dedicated support |

Quota is checked and enforced per plan. `402` is returned when exhausted.

---

## 15. Registries & links

- MCP Marketplace: https://mcp-marketplace.io/server/io-github-synapselayer-synapse-layer
- Smithery: https://smithery.ai/server/synapselayer/synapselayer
- PyPI: https://pypi.org/project/synapse-layer/
- npm: https://www.npmjs.com/package/synapse-layer
- GitHub: https://github.com/SynapseLayer/synapse-layer
- Forge Dashboard: https://forge.synapselayer.org
- Documentation: https://synapselayer.org/docs
- Connect Guide: https://synapselayer.org/connect
- OpenAPI: https://synapselayer.org/api/openapi.json
- Interactive API Reference: https://synapselayer.org/api-docs
- Skill file: https://synapselayer.org/skill.md
- llms.txt (summary): https://synapselayer.org/llms.txt

---

## 16. Appendix — service health & SLOs

- `health_check` tool and SLO reporting (`slo_report`) provide latency, availability,
  and durability metrics for governance and incident response.
- Production API: https://forge.synapselayer.org