jamgate

# Jamgate

[![CI](https://github.com/amirj4m/jamgate/actions/workflows/ci.yml/badge.svg)](https://github.com/amirj4m/jamgate/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/jamgate.svg)](https://www.npmjs.com/package/jamgate)
[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)

> A neutral memory quality-gate for AI agents — **a gate, not a store.** One shared
> memory of you — who you are, how you're doing, what you're working on — that every AI
> agent reads from and writes to, kept honest at write time. Local-first, no cloud calls,
> one dependency.

One command wires Jamgate into every MCP client on your machine:

```bash
npx jamgate setup
```

[![Add to Cursor](https://img.shields.io/badge/Add%20to-Cursor-000?logo=cursor&logoColor=white)](cursor://anysphere.cursor-deeplink/mcp/install?name=jamgate&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJqYW1nYXRlIl19)
 •  one-click **Claude Desktop** bundle → the `.mcpb` on the [latest release](https://github.com/amirj4m/jamgate/releases/latest)

## The problem: memory quality, not storage

You are one person, but every AI you use is a separate island. You design with one,
research with another, code with a third — and none of them know what the others know,
so you re-explain "what I'm working on" every time.

The tools that try to fix this mostly **store everything**, so shared memory bloats with
junk: one production audit of a leading memory system found **97.8% of its stored entries
were junk** ([source](https://github.com/mem0ai/mem0/issues/4573)) — duplicates, trivia,
one-off chatter, stale states. Sharing memory is the easy part. Keeping the shared memory
*clean and current* is the unsolved part.

Jamgate sits in the **write path** and decides what deserves to be remembered, before it
is stored:

```
                 without a gate                          with Jamgate
   ┌──────────────────────────────────┐   ┌──────────────────────────────────────┐
   │ "remember I'm on a call"          │   │ ✗ rejected — not durable             │
   │ "I use Windows"  ← from 6mo ago   │   │ ⇄ superseded — "I use Linux" wins    │
   │ "I use Windows"  (again)          │   │ ✗ duplicate — already known          │
   │ "I use Linux"                     │   │ ✓ saved — durable, changes answers   │
   │ "my name is Sam" (agent guessed)  │   │ ⚠ conflict — lower trust, ask first  │
   └──────────────────────────────────┘   └──────────────────────────────────────┘
     everything piles up, 98% junk           small, current, trustworthy
```

## The idea

**Jamgate is one shared memory of you that every agent plugs into — kept honest by a
quality gate.** It runs as an [MCP](https://modelcontextprotocol.io) server, so any
MCP-capable agent (Claude Code, Claude Desktop, Cursor, …) connects to the *same* memory
on your machine. Because it filters at write time, that memory stays small, accurate, and
contradiction-free instead of bloating with junk.

```
Agent → [ Jamgate quality gate ] → local store (~/.jamgate/memory.json)
        save_memory / recall_memory / forget_memory
```

## What it does — the gate layers

A memory is kept only if it is **durable** (still true after this session) and would
**change a future answer**. The gate is a hybrid pipeline, cheapest checks first:

| Layer | What it does |
| --- | --- |
| **Rule pre-filter** | Drops obvious non-durable noise before it reaches the store: fragments, pleasantries, placeholder text (`test`, `foo bar`), and anything that isn't a claim about you. |
| **Credential refusal** | Refuses to store secrets. API keys (`sk-…`, `AKIA…`, `ghp_…`, JWTs, PEM blocks), password assignments, and high-entropy tokens next to credential wording are rejected with a reason — and kept out of the decision log too. A git sha or UUID in ordinary prose passes untouched. |
| **Question filter** | A question asks *for* memory, it isn't memory. `how much is jam's rent?` is refused; a rhetorical question inside a longer fact is not. |
| **Transience filter** | Statements pinned to this instant ("it's raining right now") are refused unless you type them as `state`, where a short TTL ages them out on their own. |
| **Agent salience** | Uses the calling agent's own understanding as the main "is this worth remembering?" filter — no extra LLM call of our own. |
| **Exact dedup** | Identical facts are never stored twice. |
| **Time-aware supersession** | Every memory is a timestamped event; a newer fact retires an older one on the same `subject` by recency — no contradiction pile-up, and it never throws your own stale words back at you. |
| **Trust hierarchy** | A lower-trust source (an agent's guess) can't silently overwrite a higher-trust fact (something you said explicitly). The gate refers the conflict back to you instead. |
| **Semantic near-dup** *(optional)* | With local embeddings on, a save that *means* the same as an existing memory returns as a `possible_duplicate` to confirm, rather than piling up. |
| **Related-memory hint** *(optional)* | Below the duplicate bar but clearly on the same topic, the memory is **stored** and the look-alike is named, so the agent can re-save with a shared `subject` if it was really an update. A hint never retires anything. |
| **Type-based expiry** | Volatile state ages out (~2 days) while identity never does, so recall stays current automatically. |

Every rejection comes back with a reason the calling agent can act on — the agent is the
only party able to correct the call, and a bare "rejected" just teaches it to work around
the gate.

Everything is taggable, expirable, and deletable — you always see and control what's
remembered.

## Quick start

Jamgate runs **locally** — your memory never leaves your machine. Requires Node.js 20+.
No install step: `npx` fetches and runs it on demand.

### Option A — `npx jamgate setup` (recommended)

One command detects the MCP clients installed on your machine (Claude Code, Claude Desktop,
Cursor, Windsurf, Gemini CLI, VS Code / Copilot, Cline, Roo Code, OpenCode, Zed) and wires
Jamgate into each:

```bash
npx jamgate setup
```

It is **safe to run**: idempotent (running it twice changes nothing), it never touches any
server entry but its own, and it backs up each config file to `<file>.jamgate-backup` before
writing. A plain `setup` (local stdio) will also **never silently overwrite a remote (`--remote`)
wiring** — it leaves that client as-is and tells you so; pass `--force` to downgrade it on
purpose. Useful flags:

```bash
npx jamgate setup --dry-run                          # show what would change, write nothing
npx jamgate setup --remote https://you/mcp --token … # wire HTTP transport (see Remote mode)
npx jamgate setup --force                             # overwrite even a remote wiring with local stdio
npx jamgate status                                    # show which clients are wired + where the store lives
npx jamgate --help                                    # every command and environment variable
```

If `setup` finds no clients, that is normal on a machine where the client has been installed
but never launched — a client writes its config on first run. Start it once, then re-run
`npx jamgate setup`.

Restart your client(s) afterwards. On Claude Code, when the `claude` CLI is present, setup
uses `claude mcp add` under the hood; otherwise it merges `~/.claude.json` directly.

### Option B — per-client manual

Prefer to wire it yourself? Each client is a small config change.

**Claude Code:**

```bash
claude mcp add jamgate -- npx jamgate
```

**Claude Desktop** — one-click: download the `.mcpb` bundle from the
[latest release](https://github.com/amirj4m/jamgate/releases/latest) and open it (Claude
Desktop → Settings → Extensions; the bundle is unsigned, so you may see an "unverified"
prompt). Or add to `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "jamgate": {
      "command": "npx",
      "args": ["jamgate"]
    }
  }
}
```

**Cursor** — click the **Add to Cursor** badge at the top, or add to `~/.cursor/mcp.json`
(or `.cursor/mcp.json` in a project):

```json
{
  "mcpServers": {
    "jamgate": {
      "command": "npx",
      "args": ["jamgate"]
    }
  }
}
```

**Windsurf** — add the same `mcpServers` block to `~/.codeium/windsurf/mcp_config.json`.

**Gemini CLI** — add the same `mcpServers` block to `~/.gemini/settings.json`.

**Cline / Roo Code** — add the same `mcpServers` block to the extension's MCP settings file
(Cline: `.../globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`; Roo:
`.../globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json`), or use each
extension's "Configure/Edit MCP Servers" button.

**VS Code (Copilot)** — add to the user `mcp.json` (Command Palette → **MCP: Open User
Configuration**). VS Code uses a `servers` key and an explicit `type`:

```json
{
  "servers": {
    "jamgate": { "type": "stdio", "command": "npx", "args": ["jamgate"] }
  }
}
```

**OpenCode** — add to `~/.config/opencode/opencode.json` under the `mcp` key (note the single
`command` array and `enabled` flag):

```json
{
  "mcp": {
    "jamgate": { "type": "local", "command": ["npx", "jamgate"], "enabled": true }
  }
}
```

**Zed** — add to `settings.json` under `context_servers`:

```json
{
  "context_servers": {
    "jamgate": { "command": "npx", "args": ["jamgate"] }
  }
}
```

#### Supported agents

`jamgate setup` auto-wires every agent below whose MCP config it can merge **losslessly** —
each entry shape is verified against the vendor's official docs. Agents whose config lives in a
non-JSON format we can't safely round-trip (TOML / YAML) are listed as **manual** with the
one-liner to add yourself.

| Agent | Config file | `setup` | Remote (`--remote`) |
| --- | --- | --- | --- |
| Claude Code | `~/.claude.json` | ✅ auto | ✅ |
| Claude Desktop | `claude_desktop_config.json` | ✅ auto | connectors UI |
| Cursor | `~/.cursor/mcp.jso