A neutral, cross-agent memory quality gate for AI agents, delivered as an MCP server — a gate, not a store.
Every AI tool I use keeps its own memory, so I kept re-introducing myself to all of them. Jamgate is one memory file on my machine that any MCP client can read and write, with a quality gate in front deciding what actually gets written. It runs locally and has one runtime dependency.
I built it for myself and I'm the only person who has used it in anger, which is worth knowing before you read the rest. What it can't do is a section, not a footnote.
One command wires it into every MCP client on your machine:
npx jamgate setup
.mcpb on the latest release
Sharing memory between agents turns out to be the easy half. I had a working shared store early on and the problem it created was worse than the one it solved: within a week it was full of "jam is on a call", the same fact three times in slightly different words, and a stale preference from a month earlier being handed to an agent as though it were current.
The clearest public example of where this ends up is mem0 issue #4573, where a user audited their own production store of 10,134 entries by hand. The detail I keep coming back to is this one: 808 entries asserting "User prefers Vim". Nobody in that system used Vim. The extraction model hallucinated it once, it got stored, it came back in the next session's recall context, and the pipeline re-extracted it from its own output as though it were a fresh fact.
Read that report carefully before you lean on it, though. It is one person, one agent, 32 days, and a 2-billion-parameter local model did the extraction for the first 20 of those days. The headline "97.8% junk" is dominated by that weak model; in the batch extracted by a frontier model the rate was 89.6%. The issue is now closed, and a mem0 maintainer has since described changes shipped in April 2026 aimed squarely at these problems.
So I don't want to lean on the percentage, and this README used to. The part that survives all of those caveats is structural, and no model upgrade fixes it: if there is nothing between extraction and storage, a hallucination that gets stored once will be re-extracted forever. A better model changes how articulate the junk is. Sharing that memory across every agent you own just distributes it faster.
So Jamgate sits in the write path and decides what gets 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 │
└──────────────────────────────────┘ └──────────────────────────────────────┘
it all piles up, forever small, and still true
It runs as an MCP server, so any MCP client (Claude Code, Claude Desktop, Cursor, and seven others) talks to the same memory file on your machine.
Agent → [ Jamgate quality gate ] → local store (~/.jamgate/memory.json)
save_memory / recall_memory / forget_memory
A memory is kept if it is still true after this session and would change a future answer. Cheapest checks run 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 (or volatility: "fast"), where recall describes them as short-lived rather than treating them as standing facts. |
| Agent salience | Uses the calling agent's own understanding as the main "is this worth remembering?" filter — no second LLM call of its own. |
| Thin classifier (built, and inert on most clients today) | For the few saves a rule finds genuinely ambiguous, the gate asks your agent's own model one closed question over MCP sampling, so there is no API key, no vendor and nothing to pay for. It catches two things a rule cannot: text that announces itself as scaffolding (safe to delete, temporary test entry), and a long volatile save that is really a permanent fact and would be described as short-lived. It can only tighten a verdict, never loosen one, and it never sees any memory but the one being saved. Sampling is optional in MCP and most clients do not implement it. Claude Code declares roots and elicitation and no sampling, so for most people today this layer never runs at all and the gate is rules-only. See Honest limits. |
| 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 topic by recency — no contradiction pile-up, and it never throws your own stale words back at you. The retired one is archived, not deleted: jamgate archive reads it, jamgate restore brings it back. |
| 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 related, the memory is stored and the look-alike is named, so the agent can re-save under the shared topic if it was really an update. A hint never retires anything. |
| Topic resolution | Identity is a topic, not the free-text string you happened to type. Your subject is a hint that proposes; the gate resolves it against the topics already in the store. Only two tiers of evidence may retire another record — you declared the topic, or the gate matched it confidently — and the tier is stored on the record, so a bad call is auditable rather than invisible. When the gate is not confident it says so and lists the topics your memory might have belonged to, which is the cheapest thing in here and the one that prevents the most damage. |
| Freshness, not expiry | volatility says how fast this kind of fact changes: stable never goes stale, slow is about three months, fast about two days, unknown has no window at all. Past its window a memory is still returned, marked stale, and ranked below every fresh match. Nothing is hidden and nothing is deleted. Re-saving under the same topic with a durable volatility corrects the description retroactively. |
Every rejection comes back with a reason the calling agent can act on. This matters more than it sounds: the agent is the only party in a position to fix the call, and a bare "rejected" just teaches it to retry with slightly different wording until something sticks.
Note what is not in that table: nothing here understands your memory. These are rules, regexes and cosine thresholds. See Honest limits.
Since 0.19.0 this is structural rather than a policy. forget_memory archives: the memory
leaves recall, keeps its full text, and the reply tells the calling agent how to get it back.
Supersession archives. There is no expiry clock, so nothing ages out to nowhere. The single
remaining scheduled movement — an agent-inferred fast record past its window plus a 30-day
grace — moves it to the archive too, and never touches anything you asked for.
Exactly one command removes bytes: jamgate purge <id>. It is on the command line and the
REST API and deliberately not on the MCP surface, so no connected agent can reach it. That
asymmetry is the whole bargain — the system may never destroy; you always may — and it exists
for two reasons: a credential that gets past the detector has to be removable, and your data has
to be yours to delete.
jamgate archive # everything that left recall, and why
jamgate restore <id> # bring one back, keeping its original date
jamgate purge <id> # destroy one, permanently. Asks first, and shows you the text
jamgate topics # the topic namespace your memory is organised by
jamgate index --rebuild # rebuild the derivable caches. Never needed; never harmful
jamgate events # every operation: saves, recalls, forgets, archives, restores
Read this before the feature list, not after it. Everything below is measured or observed, and none of it is fixed yet.
Recall often puts the wrong memory first. On my own store — 12 real memories, 17 queries I wrote — the right memory came back at rank 1 in 10 of 17 cases, and appeared anywhere in the top 5 in 13. Turning on the optional embeddings used to make this worse than leaving them off; that's fixed, but "the answer is in there somewhere" is still an accurate description of recall on a store of any size. This is the weakest part of the project and the thing I'd fix next.
One specific failure inside that has been fixed, because it was worse than "imprecise": a
memory past its freshness window could outrank the memory that corrected it. Asking the same
question about money six ways, four of six returned the superseded figure first. Freshness
is now a tier, so nothing past its window outranks anything inside one. It is not "newest
wins": an identity fact never expires, so it is never stale and ranks on relevance exactly as
it did.
That fix then caused the same failure in reverse, which is worth admitting in full. A tier
that reorders everything a query matched will push a record off the end of a five-result reply,
and "ranked last of twenty-eight" is indistinguishable from hidden. Three days after shipping
the tier I measured the same store again: the record holding my current motorbike balance —
newer, and past its window only because it was filed fast — came back at rank 20 of 20, 28 of
28 and 27 of 27 across fourteen phrasings, never once inside a default reply, while the
superseded figure led every single one. In 0.20.0 relevance decides which records the reply
contains and freshness decides where they sit in it; the current figure now appears in 9 of
14 phrasings, up from 0. Five phrasings still miss it, and those are the ordinary dilution
weakness below rather than anything freshness can fix.
What is not fixed is the general ordering problem above, or contradiction detection
across two different topics — two live records can still assert different numbers for the same
thing and nothing notices. That last one is now a measured limit rather than an unbuilt
feature: four rule-based detectors were implemented and run against the real store, and every
one either drowned in false positives (4–76 flagged pairs) or missed the case it existed for,
and several did both. It is delegated to a review loop that is designed and not yet built. For scale: Letta measured plain files plus grep at 74.0% on LoCoMo
against Mem0's 68.5%, and I have no reason to think Jamgate's retrieval would beat either.
See How it compares, where grep gets its own column.
Ranking has produced a wrong answer about money, not just a wrong order. Asked "how much do I still owe on the motorbike", recall returned a 6 August balance at rank 1 and missed the 8 August one entirely — both live, both in the store, €250 apart. This is the same weakness as the row above, but it is worth stating separately because "the answer is in there somewhere" stops being an acceptable description once the answer is someone's finances.
Where it stands after 0.20.0, measured on fourteen phrasings rather than the original six so the number is not fitted to the test: the record carrying the current figure is now in the reply 9 times out of 14, where it was in 0. Every returned line also carries its date and its topic, so an agent can say "as of 6 August" instead of stating a figure flat. But the system still does not know which number is right, and it does not pretend to — the two records sit under different topics, and four rule-based detectors were built and measured before concluding that no local rule can link them. See D-077, D-080.
A name written in one script could not be found by its spelling in the other — fixed in
0.20.0, lexically only. Matching was token-based and script-literal. Measured on my own store,
on names recorded in Latin inside a Persian-speaking user's memory: Rahman and Iraj each
returned the right record at rank 1 for every natural English phrasing, and رحمان, ایرج,
سجاد, سپیده returned nothing at all — 0 of 6. For a bilingual user that is
data-loss-equivalent: the memory is there, correct, and unreachable in half the languages they
actually type.
Both scripts now fold to a shared consonant skeleton, so رحمان and Rahman are one index key.
The same six queries return the right record 6 of 6 (four at rank 1 or 2). The two paths
that already worked are unchanged, and by construction rather than by luck — the bridge only
ever fires between scripts, so two Latin words that happen to fold alike (canal, kennel)
never match each other. Re-measured after the change: Latin→Latin 5 of 5, Persian→Persian 4 of
4, and 37 of 37 unrelated labelled queries returned byte-identical ranks.
It is a lexical bridge and nothing more. Cross-script semantic recall is unchanged and still does not work: the bundled embedding model is English-only (see below). A name is findable now; a paraphrase in the other script is not. See D-075, D-080.
Nobody outside me has installed it. Many releases, ten supported clients, one user.
I've simulated a cold install (fresh HOME, empty npm cache, published package rather than
my working copy) and it held up, but simulation is not a stranger on their own machine.
macOS and Windows have never actually been run. Their config paths are unit-tested and
CI is Linux-only. If you are on a Mac and jamgate setup writes to the wrong place, you are
the first person to find out. Please open an issue.
Embeddings only attach when a memory is saved. Install the optional semantic package
today and every memory you saved before that stays invisible to semantic recall until you
save it again. There is no reindex command. This is a straightforward gap, not a hard
problem, and it isn't done.
"Store-agnostic" is a seam, not a feature. Everything above src/store/ depends on a
MemoryStore interface rather than a concrete backend, which is a real design property you
can check in the source. But the bundled file store is the only implementation. There is no
mem0 adapter, no Graphiti adapter, and no way for you to point Jamgate at your own store
today. If a future write-up of mine implies otherwise, this line is the correct one.
The quality judgments are rules and numbers, not understanding. The gate cannot tell that "moved to Berlin last spring" and "no longer lives in Athens" are the same event. It matches subjects, compares cosines against thresholds I set from measurements, and applies regexes. It is genuinely good at the mechanical cases — exact duplicates, credentials, recency on a shared subject — and blind to anything requiring judgment.
The thin classifier ships in this release and does nothing on most machines. It is built
and it is measured: 96.4% accuracy (27 of 28) on a labelled corpus, no real memory refused in
any recorded run, and it routes about 30% of decisions. But it works by asking the calling
client's own model over MCP sampling, sampling is optional in the protocol, and most clients
have not implemented it — Claude Code declares roots and elicitation and no sampling.
So unless your client samples, this layer never runs and your gate is the rules-only gate
described above. I have not seen it change a single real save of my own, because every client
I use is in that group. Treat the measurements as evidence the thing works when it is asked,
not as evidence it is working for you.
One JSON file, read whole on every operation. At my ~60 records that is free. There is no index and no pagination, so at some size it stops being free. It is now measured rather than guessed at (D-078), with embeddings off, growing a store to 10,000 records:
| records | file | one save | one recall |
|---|---|---|---|
| 100 | 0.1 MB | 5 ms | 12 ms |
| 1,000 | 0.6 MB | 19 ms | 71 ms |
| 5,000 | 3.1 MB | 52 ms | 399 ms |
| 10,000 | 6.1 MB | 110 ms | 758 ms |
Nothing breaks — no crash, no corruption, no lock failure; it degrades linearly. Recall hurts first, because it scores every record: perceptible past ~2,000 records and unpleasant past ~6,000. With embeddings on, every save also embeds and the near-duplicate scan compares all vectors, so treat these as the optimistic bound.
Semantic search is English-only. The bundled model is all-MiniLM-L6-v2. On other
scripts its similarity degenerates into "is this the same language" (the Greek for bicycle
scored 0.62 against an unrelated Greek memory), so non-Latin text is deliberately not
embedded at all and falls back to lexical matching, which does work in every script.
A memory is text, and recall puts it into your agent's context. The gate decides whether
something is worth keeping, not whether it is safe to act on. If a memory contains
instructions, those words come back verbatim on the next recall, in a place the model reads.
That is true of every memory system. Jamgate narrows the surface — it never scrapes screens,
never mines chat logs, refuses credentials, and only writes on an explicit save_memory
call — but it cannot make text inert. Treat the store as trusted input and look at what goes
in; jamgate export prints all of it.
Remote mode has its own set of limits, listed under Remote mode.
Jamgate runs locally — your memory never leaves your machine. Requires Node.js 20+.
No install step: npx fetches and runs it on demand.
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:
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:
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.
Prefer to wire it yourself? Each client is a small config change.
Claude Code:
claude mcp add jamgate -- npx jamgate
Claude Desktop — one-click: download the .mcpb bundle from the
latest release 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):
{
"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):
{
"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:
{
"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):
{
"mcp": {
"jamgate": { "type": "local", "command": ["npx", "jamgate"], "enabled": true }
}
}
Zed — add to settings.json under context_servers:
{
"context_servers": {
"jamgate": { "command": "npx", "args": ["jamgate"] }
}
}
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 I 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.json | ✅ auto | ✅ |
| Windsurf | ~/.codeium/windsurf/mcp_config.json | ✅ auto | ✅ |
| Gemini CLI | ~/.gemini/settings.json | ✅ auto | ✅ |
| VS Code (Copilot) | <Code>/User/mcp.json | ✅ auto | ✅ |
| Cline | .../saoudrizwan.claude-dev/settings/cline_mcp_settings.json | ✅ auto | ✅ |
| Roo Code | .../rooveterinaryinc.roo-cline/settings/mcp_settings.json | ✅ auto | ✅ |
| OpenCode | ~/.config/opencode/opencode.json | ✅ auto | ✅ |
| Zed | ~/.config/zed/settings.json | ✅ auto | ✅ |
| Codex CLI | ~/.codex/config.toml (TOML) | manual¹ | — |
| Goose | ~/.config/goose/config.yaml (YAML) | manual¹ | — |
| Continue | ~/.continue/config.yaml (YAML) | manual¹ | — |
¹ Manual — these use TOML/YAML; rather than risk mangling comments or formatting I don't
auto-edit them. Add Jamgate by hand: Codex CLI →
[mcp_servers.jamgate] with command = "npx" and args = ["jamgate"] in ~/.codex/config.toml;
Goose → a stdio extension under extensions: with cmd: npx / args: ["jamgate"];
Continue → an mcpServers: list entry with command: npx / args: [jamgate].
For agents that live in a shared, comment-friendly settings file (Gemini, OpenCode, Zed),
setupwill skip rather than overwrite a file it can't parse as strict JSON — so a//-commentedsettings.jsonis never clobbered; add the block by hand in that case.
Restart the agent. It now has three tools:
save_memory — store a durable fact. The gate rejects junk, drops exact
duplicates, supersedes outdated facts by recency (pass a subject like
operating-system so a newer fact retires the older one — or let the gate derive one),
and refers trust conflicts back to you. Topics are lowercase and hyphenated; dots,
underscores and spaces fold to hyphens, so editor.theme and editor-theme are one key.
type still works and always will — it translates to volatility + category at the
boundary, so a client written against any earlier version keeps working unchanged.recall_memory — fetch what's known, relevant to a query. Add includeArchived: true
to search what has left recall.forget_memory — archive a memory by the id recall_memory printed (the full id, or
an unambiguous prefix of 8+ characters). It stops being returned and is never deleted.Nothing ages out to nowhere. A memory past its freshness window is still returned and marked
stale; jamgate expired lists what is past its window, and nothing is modified:
jamgate expired # what is past its freshness window (still recallable)
jamgate expired --json # machine-readable, for a script
Your memory lives in ~/.jamgate/memory.json. Same machine, every agent → one shared
memory. To share one memory across different machines and your phone, see
Remote mode.
The worst failure mode of a memory that lives in two places is that nothing tells you. One client stays wired to the local stdio store, every save there succeeds, and you accumulate a second memory you don't know about. That happened to me: four days, seven memories, found only by a scheduled check.
Two things now make it loud rather than silent:
jamgate status # warns ⚠ SPLIT MEMORY if clients disagree
jamgate retire --to https://your-instance/mcp # the old store refuses writes from now on
jamgate status compares every wired client and says so when some point at a remote instance
while others write locally. jamgate retire marks the store — so any client that later gets
wired back to it fails with an error naming the real instance instead of quietly writing there.
Reads keep working and nothing is deleted, so a retired store is still fully readable; it
just stops being a place new memories can land. jamgate retire --status reports the state and
changes nothing.
The marker is written twice, deliberately: inside the store file (so it travels when the file
is copied) and as a <store>.retired sidecar. The sidecar exists because a Jamgate older
than 0.14.0 serializes the store without the in-file field and silently erases it on the first
write — which is exactly what a stale server did to my own retired store. If the sidecar is
there and the in-file marker is gone, jamgate status tells you an old build is still writing
and you need to stop the process, not just remove its config entry.
Removing a client's config entry does not kill a server it already started. That is worth
knowing because jamgate status reads config files: it will say "no split" while a stale
process keeps serving the old store to a live client.
jamgate setup also refuses to add a local store when another client already points at a
remote one, so the split cannot be created by accident (--force if you truly want two).
memory-disciplineWiring in the three tools gives an agent the ability to remember. The
memory-discipline skill teaches it the habits — recall before answering,
save one granular durable fact at a time with a specific reused subject, never send
secrets, and treat gate verdicts as answers rather than errors to retry. Its rules are
distilled straight from Jamgate's own decision log (D-040…D-045).
It ships in this repo at skills/memory-discipline/SKILL.md
as a portable agentskills.io instruction pack. One command installs it
for every agent the skills CLI finds on your machine (it wired 17, including Cursor, Copilot
and Claude Code, on the machine I tested it on):
npx skills add amirj4m/jamgate
The skill is prompt text, not code — it is not part of the npm package (the
files whitelist ships only dist), so it never bloats the runtime install.
By default, recall is fuzzy lexical matching (stemming, typo-tolerance, trigrams) —
fast, deterministic, and dependency-free, but blind to synonyms. It works in any script:
Persian, Greek, Cyrillic, Arabic, Hebrew, Chinese, Japanese and Korean all tokenize and
recall, and accents fold so café and cafe find each other. (Stemming is English-only, and
Chinese/Japanese are segmented per character rather than per word — good enough to find a term
inside a sentence, not a real word segmenter.) To also match on
meaning (so "automobile" recalls a memory about your "car"), install the optional
embedding backend:
npm install @huggingface/transformers
On first use it downloads all-MiniLM-L6-v2 and runs it entirely on your machine — no text is
ever sent to any cloud AI. Budget about 90 MB for that download: this README used to say
"~23 MB, quantized", which was wrong on both counts. Transformers.js fetches the fp32 model by
default and the cached directory measures 87 MB on disk, so on a small VPS or a metered
connection, plan for the real number. With the model in place, recall blends semantic
similarity into the ranking, and a save that means the same as an existing memory comes back as
a possible_duplicate for you to confirm. If the package isn't installed, Jamgate runs on
fuzzy recall and nothing breaks.
What to expect from it, measured rather than assumed (D-063): the thresholds are set from real cosines on this model over a real store, not from estimates. Two limits are worth knowing before you install it:
By default Jamgate is single-tenant: one human, one memory. If you need one instance to hold
several memories that must not blend — a tutor app with separate subjects, or a small group
sharing an instance — attach an optional scope (an opaque label such as amir/greek) to a
memory and to each operation:
default namespace, which is exactly how Jamgate behaved before namespaces existed. Nothing
changes for a single-user setup.Over MCP, pass scope on save_memory / recall_memory / forget_memory. Over the REST API
(below), pass it in the JSON body or as a ?scope= query parameter. Scopes are just
case/whitespace-folded labels — user/role is a useful convention, not a required format.
Multi-user separation (per-person accounts and auth) is a different thing and is not what a scope provides: whoever holds the
JAMGATE_TOKENcan address any scope on that instance. A scope is a namespace within one token-holder's memory.
All configuration is via environment variables; every one has a sensible default.
| Variable | Default | What it does |
|---|---|---|
JAMGATE_STORE | ~/.jamgate/memory.json | Path to the memory store file. |
JAMGATE_EMBEDDINGS | auto | off disables the semantic layer even if the model is installed. |
JAMGATE_DUP_THRESHOLD | 0.88 | Semantic near-duplicate sensitivity (0–1); higher = stricter. Measured against the real model, true rewordings span ~0.76–0.94 and different facts reach ~0.81, so the two overlap — 0.88 deliberately favours never refusing a real memory over catching every reword. |
JAMGATE_GATE_LOG | on | off disables the local decision log. |
JAMGATE_CLASSIFIER | on | off disables the thin classifier outright — no sampling request is ever sent and the gate runs rules-only. It is already inert on any client that doesn't support MCP sampling. |
JAMGATE_CLASSIFIER_TIMEOUT_MS | 8000 | How long a save may wait for the classifier's answer before giving up and saving as rules-only. A save is never blocked on a model. |
JAMGATE_WINDOW_<VOLATILITY>_DAYS | per volatility | Override a freshness window, e.g. JAMGATE_WINDOW_SLOW_DAYS=180. never/none disables one. The v1 names (JAMGATE_TTL_PROJECT_DAYS, JAMGATE_TTL_STATE_DAYS, …) are still honoured and map onto the same windows. |
JAMGATE_EVENT_LOG | on | Where the operation log goes. Resolved from JAMGATE_STORE by default (never independently from $HOME); off disables it. |
JAMGATE_HTTP | off | 1/true enables remote mode (same as the --http flag). |
JAMGATE_PORT | 8420 | Port for remote mode (same as --port). |
JAMGATE_HOST | 127.0.0.1 | Interface to bind in remote mode. Keep it on localhost behind a reverse proxy. |
JAMGATE_TOKEN | — | Bearer token required in remote mode. The server refuses to start without it. |
JAMGATE_OAUTH | on | In remote mode, serve the MCP OAuth flow so claude.ai / the Claude app can connect. off disables it (static-token-only). |
JAMGATE_OAUTH_STORE | ~/.jamgate/oauth.json | Path to the OAuth state file (registered clients + hashed tokens). |
A store created by 0.19.0 or later splits by how often each part is read:
| File | What | Read when |
|---|---|---|
memory.json | the live memories, no vectors — still plain JSON you can cat | every save and recall |
archive.jsonl | everything that left recall, full text, with the reason | only when you ask |
events/events-YYYY-MM.jsonl | every operation, rotated by month, never overwritten | never, normally |
vectors.f32 | the embeddings, as binary | startup |
index.json | topic registry, text hashes, and the inverted index recall searches | startup |
Only the first three are data. The last two are caches: delete them and nothing is lost —
they rebuild, and jamgate index --rebuild does it on demand. On my own store the file read on
every single operation went from 843.5 KB to 75.1 KB, because 88.1% of it was embedding
vectors written out as pretty-printed JSON, and a quarter of the whole file was the whitespace
inside those arrays.
index.json grew to 81 KB in 0.20.0 when the inverted index landed in it. Below 2,000 memories
recall still reads every record as well, because at that size a full scan costs under a
millisecond and completeness is worth more than latency. Above it the index does the bounding:
measured on a synthetic 6,000-record store, a recall went from scoring 6,000 candidates in
1,542 ms to scoring 238 in 54 ms.
Nothing converts on its own. An existing store keeps working exactly as it is — with every v2 behaviour, just in one file — until you run the migration deliberately:
jamgate migrate --dry-run # build, verify, write nothing. Run this and read it
jamgate migrate # convert, after five gates pass
jamgate migrate --rollback # go back to the single-file layout
Five gates run before the old file is renamed, and all must pass: every record accounted for, every text byte-identical, no supersession pointer broken, the same queries returning the same records in the same order on both layouts, and the rollback executed and diffed against the original before going forward. A verified backup (SHA-256 + parse check) is taken first, and your v1 file is preserved rather than replaced. If any gate fails, nothing is renamed.
Your memory is a JSON file (JAMGATE_STORE, default ~/.jamgate/memory.json), so a backup can
be as simple as copying it — plus the two .jsonl files beside it, if you have migrated. But jamgate export / jamgate import do it properly — schema-aware,
and with import passing every record back through the same quality gate so a restore or a
machine-to-machine move can't smuggle in duplicates or overwrite a trusted fact.
# Back up everything (active + superseded history) to a file
jamgate export --output backup.json
# Only the live facts, and pipe it somewhere
jamgate export --active-only > my-memory.json
# Restore / merge into another machine's store (respects JAMGATE_STORE)
jamgate import backup.json
# See exactly what would happen first — nothing is written
jamgate import backup.json --dry-run
Export writes a { schemaVersion, exportedAt, generator, memories } envelope. Without
--output it prints pure JSON to stdout (so it pipes cleanly) and the summary to stderr.
Import accepts that envelope or a bare JSON array. Each active record is replayed through the
gate — exact-duplicate dedup, time-aware supersession, the trust/contradiction guard, and
near-duplicate detection — instead of being blindly appended, and original timestamps and
provenance are preserved (your createdAt is never reset). It prints a per-record report
(imported / duplicates skipped / superseded / conflicts flagged / near-duplicates); conflicts and
near-duplicates are surfaced for you to decide, never silently resolved. The whole import is one
atomic transaction — a malformed file is rejected with a nonzero exit and your store is left
untouched. Records already retired (superseded) in the source are treated as history and skipped,
not re-activated. See DECISIONS D-033.
Moving a local store onto your own server? Export locally, copy the JSON up, then
JAMGATE_STORE=/data/memory.json jamgate import my-memory.jsonon the box (or just place the file atJAMGATE_STORE— butimportis what merges into an existing server store safely).
If you've been using Claude or ChatGPT for a while, they already know things about you, and
starting from an empty file is the annoying part of trying anything new.
jamgate import --from <vendor> takes the memory list you copy out of either one and replays
it through the same gate a live save goes through, so duplicates and junk don't come along
with it.
# Claude — a memory list you saved from Settings → Capabilities → "View and edit your memory"
jamgate import --from claude ~/Downloads/claude-memory.md
# ChatGPT — the list copied from Settings → Personalization → Memory → "Manage memories"
jamgate import --from chatgpt ~/Downloads/chatgpt-memory.txt
# Point it at the export .zip or the extracted folder — it finds the memory file inside
jamgate import --from chatgpt ~/Downloads/chatgpt-export.zip
# Always look first. Nothing is written on a dry run.
jamgate import --from claude ~/Downloads/claude-memory.md --dry-run
Honest status, checked July 2026: neither vendor's bulk account data export contains your memory entries. Both keep them in the app's own memory settings, and both document a copy-out-the-text path. So the file you feed Jamgate is a text/markdown list, one memory per line:
| Product | Where your memories are | What to do |
|---|---|---|
| Claude | Settings → Capabilities → "View and edit your memory" | Copy the list (or ask Claude: "Write out your memories of me verbatim, exactly as they appear in your memory") into a .md/.txt file. Anthropic's own memory-transfer format is [date saved, if available] - memory content — which is what the parser expects. |
| ChatGPT | Settings → Personalization → Memory → "Manage memories" | Select the list and copy it into a .md/.txt file. A trailing (saved 2026-01-09) is understood. |
Dates are optional. Bullets (-, *, 1.), markdown headings, horizontal rules and code fences
are handled. If a future export does ship structured memory JSON, it reads that too —
best-effort, looking for entries under memory-ish keys — and it accepts the .zip or the extracted
folder directly and pick the memory-shaped file out of it.
conversations.json, chat.html,
message_feedback.json and friends are recognized by name, skipped, and reported as skipped.
Inferring facts about you from raw chat history is exactly the low-consent behavior this project
exists to push back on. If the export contains nothing but chat logs, the import fails with a
message telling you where your memories actually live.Every parsed line becomes a memory and goes through the gate, never blind-appended:
user-confirmed — you curated these in the source product. Not user-explicit
(you didn't dictate them to Jamgate), not agent-inferred (they aren't a guess by this tool).preference or identity only when the wording is obvious;
otherwise left untyped. A wrong type is worse than no type.import:claude.ai / import:chatgpt, so you can always see where a
memory came from.Because a hand-pasted file can contain stray prose (a footer, a stray note), every non-empty line
is a candidate. Run --dry-run first — it prints exactly what would land. See
DECISIONS D-035.
Want one shared memory across your phone, browser, and laptop but don't want to run a server? Click a button, log into a hosting platform, and you get your own Jamgate instance with its own URL and token — no terminal, no server knowledge. Same gate, same store as the local install; only the transport is over the network (this is Remote mode, set up for you).
What you should know first (honest version):
The button reads render.yaml straight from this repo: it builds the image from
the Dockerfile, generates a random JAMGATE_TOKEN for you, and attaches a
1 GB persistent disk at /data for your memory. Render provisions a paid starter instance
(a disk needs one). After it goes live, read your token under Environment, and your URL is
the service URL with /mcp appended (e.g. https://jamgate-xxxx.onrender.com/mcp).
The button deploys the published template: it builds the image from the Dockerfile
(pinned via railway.json with the /healthz check), generates a random
JAMGATE_TOKEN for you, and attaches a persistent volume at /data for your memory. After it
goes live, read your token under Variables, and your URL is the service domain with /mcp
appended (e.g. https://jamgate-xxxx.up.railway.app/mcp).
Once the deploy is live you have two things: a URL ending in /mcp and a token (from the
platform's environment/variables tab). Connect each device to the same instance so they share one
memory:
Desktops (Claude Code, Cursor, Windsurf, Gemini CLI, VS Code, Cline, Roo Code, OpenCode, Zed) — one command:
npx jamgate setup --remote https://your-instance/mcp --token <your-token>
This wires every detected client on that machine to your instance (Streamable HTTP clients only; others — e.g. Claude Desktop — are skipped with a reason).
Phone (Claude app) and claude.ai in a browser: Settings → Connectors → Add custom
connector → URL https://your-instance/mcp, and provide the bearer token when asked. The same
three tools (save_memory, recall_memory, forget_memory) then work from your phone.
Save on your phone, recall on your laptop — one memory, everywhere. For the full server-owner path (your own VPS, systemd + Caddy), keep reading.
By default Jamgate runs locally over stdio — one process per agent, on your machine, no network. That's the right model for a single computer. But you are one person with agents in several places at once: the Claude app on your phone, claude.ai in a browser, Claude Code on a laptop. stdio can't be their shared brain — each would get its own local process and its own memory.
Remote mode is the answer: run one Jamgate instance on a server you control, put it behind HTTPS, and point every agent at the same URL. Now they share one memory of you — save on your phone, recall on your laptop. It's the same gate and the same store, just reachable over the network. It stays opt-in; stdio remains the default and the local-first promise is unchanged. Whether it's your own memory or a whole team's, the rule is one instance per person (see Honest limits).
# A strong token is REQUIRED — the server refuses to start without one.
export JAMGATE_TOKEN=$(openssl rand -hex 32)
jamgate --http # listens on 127.0.0.1:8420/mcp
# or: jamgate --http --port 9000 (or JAMGATE_HTTP=1 JAMGATE_PORT=9000)
The MCP endpoint is /mcp. Every request must carry Authorization: Bearer <token>; anything
else gets a 401. In remote mode Jamgate also serves the standard MCP OAuth flow (on by
default) so it can be added to claude.ai and the Claude mobile app — see
Adding to claude.ai.
JAMGATE_TOKEN guards every request, compared in
constant time so it can't be recovered from response timing. Generate it with
openssl rand -hex 32, keep it out of shell history, and rotate it by restarting with a new
value.127.0.0.1 by default, so it is never directly exposed. Put caddy or nginx in
front to terminate HTTPS and forward to it locally. A bearer token over plain HTTP on the open
internet is a leaked token — always run it behind TLS.JAMGATE_TOKEN is still the only
credential, PKCE is enforced, and issued tokens are stored hashed and revocable. Details in
Adding to claude.ai.MCP is the right protocol for agents, but an ordinary app backend just wants plain HTTP. In remote mode Jamgate also serves a small REST API on the same port, behind the same bearer token — so a mobile app or a script can save and recall without speaking JSON-RPC:
BASE=https://memory.example.com/v1/memory
AUTH="Authorization: Bearer $JAMGATE_TOKEN"
# Save (optionally into a namespace — see "Namespaces" above)
curl -sX POST "$BASE" -H "$AUTH" -H 'Content-Type: application/json' \
-d '{"text":"the aorist tense expresses a completed action","scope":"amir/greek","type":"project"}'
# Recall within a scope
curl -s "$BASE?query=aorist&scope=amir/greek" -H "$AUTH"
# Archive by id, within a scope — this does NOT delete
curl -sX DELETE "$BASE/<id>?scope=amir/greek" -H "$AUTH"
# Read the archive, bring one back, or destroy one permanently
curl -s "https://memory.example.com/v1/archive?query=aorist" -H "$AUTH"
curl -sX POST "$BASE/<id>/restore" -H "$AUTH"
curl -sX POST "https://memory.example.com/v1/purge/<id>" -H "$AUTH"
| Method & path | Body / query | Returns |
|---|---|---|
POST /v1/memory | {text, scope?, type?, volatility?, category?, subject?, source?} (content/memory accepted as aliases of text) | 201 with {action, memory, …} when a record lands; 200 with the gate's action when it deliberately stores nothing (duplicate/conflict/possible_duplicate/rejected) |
GET /v1/memory | ?query=&scope=&limit=&includeArchived= | 200 with {memories: […], staleCount?} |
GET /v1/memory | ?stale=1&scope= | 200 with {stale: […]} — records past their freshness window. expired=1 is kept as an alias |
DELETE /v1/memory/:id | ?scope= | 200 {ok:true, id, archived:true, restorable:true, message} — archives, never deletes. 404 not found, 409 ambiguous prefix |
GET /v1/archive | ?query=&scope=&limit= | 200 with {archive: […]} — everything that left recall, with its reason |
POST /v1/memory/:id/restore | ?scope= | 201 with the revived memory. 403 if it was redacted as a credential |
GET /v1/topics | ?scope= | 200 with {topics: […]} — the namespace, so a caller can reuse a topic instead of inventing one |
POST /v1/purge/:id | ?scope= | 200 — DESTROYS. The only route that removes bytes; deliberately not on the MCP surface |
Every REST save goes through the exact same gate as the MCP tool (dedup, topic resolution,
supersession, conflict guard, credential refusal), per scope. A missing/wrong token is a 401; a malformed
body is a 400. The MCP endpoint (/mcp) and the OAuth flow are unaffected — REST is purely
additive.
A systemd unit to keep Jamgate running (fill in your user and a real token — ideally load the
token from an EnvironmentFile with 600 permissions rather than inlining it):
# /etc/systemd/system/jamgate.service
[Unit]
Description=Jamgate MCP memory (remote mode)
After=network.target
[Service]
# Load JAMGATE_TOKEN=... (and any JAMGATE_* overrides) from a root-only file:
EnvironmentFile=/etc/jamgate.env
Environment=JAMGATE_HTTP=1
Environment=JAMGATE_PORT=8420
Environment=JAMGATE_STORE=/var/lib/jamgate/memory.json
ExecStart=/usr/bin/npx jamgate
User=jamgate
Restart=on-failure
[Install]
WantedBy=multi-user.target
echo "JAMGATE_TOKEN=$(openssl rand -hex 32)" | sudo tee /etc/jamgate.env >/dev/null
sudo chmod 600 /etc/jamgate.env
sudo systemctl enable --now jamgate
Caddy — automatic HTTPS, two lines of real config:
memory.example.com {
reverse_proxy 127.0.0.1:8420
}
nginx — equivalent, with TLS certs managed by certbot. Note that nginx, unlike Caddy's
reverse_proxy, forwards only the paths you name: every Jamgate surface needs its own
location, and one you forget returns nginx's own 404 without the request ever reaching
Jamgate.
server {
listen 443 ssl;
server_name memory.example.com;
ssl_certificate /etc/letsencrypt/live/memory.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/memory.example.com/privkey.pem;
location /mcp {
proxy_pass http://127.0.0.1:8420/mcp;
proxy_http_version 1.1;
proxy_set_header Connection ""; # keep-alive for SSE streaming
proxy_buffering off; # don't buffer the event stream
proxy_read_timeout 3600s;
}
# REST API (0.10.0). REQUIRED if you use it — without this block `/v1/memory` is a
# 404 from nginx, not a 401 from Jamgate, and every REST client silently sees "no
# such endpoint" instead of "you need a token".
location /v1/ {
proxy_pass http://127.0.0.1:8420;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header Authorization $http_authorization;
}
# MCP OAuth (needed for claude.ai and the Claude mobile app).
location /.well-known/ { proxy_pass http://127.0.0.1:8420; }
location /authorize { proxy_pass http://127.0.0.1:8420; }
location /token { proxy_pass http://127.0.0.1:8420; }
location /register { proxy_pass http://127.0.0.1:8420; }
# Liveness probe (unauthenticated by design; exposes only status + version).
location /healthz { proxy_pass http://127.0.0.1:8420/healthz; }
}
Verify each surface actually reaches Jamgate after any proxy change — an unauthenticated
request must come back 401 from Jamgate, never 404 from the proxy:
curl -si https://memory.example.com/v1/memory | head -1 # expect: HTTP/2 401
curl -s https://memory.example.com/healthz # expect: {"status":"ok","version":"…"}
Point every agent at https://your-domain/mcp with the token.
Claude app (iOS / Android / desktop) and claude.ai — Settings → Connectors → Add custom
connector → paste the URL https://your-domain/mcp and click through. These clients only speak
the standard MCP OAuth flow, so instead of pasting a token into a config field, a Jamgate
page opens in your browser and asks: "This is your Jamgate instance. Enter your instance token
to authorize this client." Paste your JAMGATE_TOKEN once, and Claude is connected — it
remembers the authorization, so you won't be asked again for that client. Once connected, the
same three tools (save_memory, recall_memory, forget_memory) are available from your phone
and browser. See Adding to claude.ai below for what happens under
the hood.
Claude Code — add it as an HTTP MCP server:
claude mcp add --transport http jamgate https://your-domain/mcp \
--header "Authorization: Bearer <token>"
Any MCP client that speaks Streamable HTTP works the same way: URL https://your-domain/mcp,
header Authorization: Bearer <token>.
claude.ai and the Claude mobile app cannot take a static token in a config field — they only
support the MCP authorization flow
(OAuth 2.1 + PKCE). Jamgate implements that flow itself in remote mode, so no external identity
provider is involved — your instance is the authorization server, and your JAMGATE_TOKEN is
the one credential. It's on by default whenever you run --http (disable with
JAMGATE_OAUTH=off if you only ever use Claude Code with a static header).
What you do:
https://your-domain/mcp.JAMGATE_TOKEN and submit. That's the
only thing it ever asks for, and only once per client.save_memory / recall_memory / forget_memory now work from that client.What happens under the hood (all served by your instance, same origin, no third party):
| Endpoint | Spec | Purpose |
|---|---|---|
GET /.well-known/oauth-protected-resource | RFC 9728 | Tells the client where the authorization server is. A 401 from /mcp also carries a WWW-Authenticate header pointing here. |
GET /.well-known/oauth-authorization-server | RFC 8414 | Advertises the endpoints below; PKCE S256 required. |
POST /register | RFC 7591 | Dynamic client registration — the client gets a client_id. |
GET/POST /authorize | OAuth 2.1 | The consent page that asks for your instance token, then issues a single-use, PKCE-bound authorization code. |
POST /token | OAuth 2.1 | Exchanges the code (+ PKCE verifier) for a long-lived access token (and a refresh token). |
Security: PKCE (S256) is mandatory, redirect URIs are matched exactly (no open redirect),
authorization codes are single-use and expire in ≤60s, and access/refresh tokens are stored
hashed in ~/.jamgate/oauth.json (revoke one by deleting its entry) with the same atomic,
locked writes as the memory store. The /mcp endpoint accepts either an issued OAuth access
token or the static JAMGATE_TOKEN, so existing Claude Code connections keep working
unchanged.
These are on top of the general limits above.
There are no benchmark numbers here. This category has had two of them retracted in public and I am not adding a third from a project with one user.
The column that should worry me most is the last one. Letta benchmarked plain markdown files
with grep and semantic search against Mem0 on LoCoMo and the files won — 74.0% versus
68.5% with GPT-4o mini
(their write-up). That is somebody
else's benchmark of somebody else's system, and Jamgate has never been run on LoCoMo, so I
cannot tell you where it would land. But the honest reading is that a directory of text files
and a twenty-year-old command-line tool is a serious baseline, and any memory product that
cannot say why it beats that baseline probably doesn't.
| Jamgate | Mem0 / OpenMemory | Zep / Graphiti | Plain files + grep | |
|---|---|---|---|---|
| Core model | Rule-based gate in front of a flat file | LLM-extracted memory layer | Temporal knowledge graph | A directory of text |
| Where memory lives | A JSON file on your machine | Hosted platform or self-hosted store | Graph server (self-hosted or cloud) | Files on your machine |
| Gate before write | Core design | Partial (dedup/update) | Partial | None |
| Duplicates | Exact + optional semantic | Yes | Yes | Pile up forever |
| Superseding an outdated fact | By subject, automatically | Partial | Yes, temporally | You edit the file |
| Source-trust hierarchy | Yes | Not that I can find | Not that I can find | No such concept |
| Expiry of volatile state | By type, automatic | Partial | Yes | Never |
| LLM calls of its own | None | Required | Required | None |
| Dependencies / infra | 1 runtime dep, no server | SDK + service/DB | Graph DB + service | Zero. You have it already |
| Retrieval quality | Weak. Fuzzy lexical + optional local embeddings; 10/17 top-1 on my own store | Real vector retrieval and reranking, tuned over many deployments | Graph traversal plus vector search | Beat Mem0 on LoCoMo (74.0 vs 68.5) |
| Understands what a memory means | No. Regexes, subject matching, cosine thresholds | Yes — LLM extraction is the whole design | Yes — entity and relationship extraction | No |
| Entity / relationship reasoning | None. Flat records with a subject string | Some | This is what it is for | None |
| Scale | Measured to 10,000 records; recall slows past ~2,000 (758 ms at 10k). One file, read whole, no index | Production deployments | Production deployments | Millions of lines, fine |
| Multi-user / teams | No. One instance, one person, one token | Yes | Yes | Whatever your filesystem does |
| Language support | Lexical recall in any script; semantic is English-only | Multilingual models | Multilingual models | Any bytes at all |
| SDKs | MCP and a small REST API | Python, TS, and more | Python, TS, and more | Every language ever written |
| Maturity | One developer, one user; see the releases | Funded team, wide adoption | Funded team, wide adoption | Older than all of us |
| Best for | One person's cross-agent memory, kept small and current, on their own disk | Application-scale memory with real retrieval | Relationship and temporal reasoning | Almost certainly your first thing to try |
Read that last column honestly: grep beats Jamgate on retrieval, scale, language support, and
every kind of maturity, and it costs nothing because you already have it. What it has no
concept of is writing — every duplicate, every contradiction and every stale fact stays in
your files until you go and edit them yourself. That is the entire bet of this project: that
for a memory several agents write to unattended, the write side is where the work is. If you
are happy curating the files yourself, curate the files yourself. You will probably get better
retrieval than I can give you.
The Jamgate column is checked by the test suite and by the measurements in
DECISIONS.md. The other two are read from those projects' public
documentation as of August 2026 and describe default behaviour, not the ceiling of what
they can be configured to do. If a row is wrong, open an issue and I will fix it — including
the ones that are unflattering to them.
Short version: if you want the best retrieval, use Mem0. If your memory is really a graph of people and events, use Zep. Jamgate is worth a look if what you want is one small memory of yourself that several agents share, on a disk you own, and you care more about it staying clean than about it being clever.
Your memories are never sent anywhere by Jamgate. There is no outbound request carrying your data, no telemetry, no accounts and no keys. Jamgate has no provider of its own to call. The store, the gate and the embedding model all run on your machine.
Two things do touch the network, both of them downloads and neither carrying your text: npx
fetching the package from npm, and — only if you installed the optional semantic package — the
embedding model's first-run download from Hugging Face (about 90 MB, then cached). Both stop
after install.
The thin classifier is the one place any of your text moves, and only on a client that
implements MCP sampling. When it fires, the gate sends one question back down the MCP
connection it is already serving, and your agent answers it with the model it was already
using. Jamgate still calls nobody. What travels is only the text of the save being judged,
never another memory, never the store, never a recall result, and it goes to the model that
just wrote that text in the same session, so it cannot disclose anything your client did not
already have. On a client without sampling it never happens at all, which today is most of
them. If you would rather it never happened anywhere, set JAMGATE_CLASSIFIER=off.
There are two local logs, both of which stay on the machine. The decision log records every
gate verdict (saved, duplicate, superseded, conflict, possible_duplicate, rejected) plus the
classifier's answer where one was consulted. The event log, new in 0.19.0, records every
operation — saves, recalls, forgets, archives, restores, purges, index rebuilds and
migrations — one line each, in events/events-YYYY-MM.jsonl beside the store, rotated by month
and never overwritten. A recall line carries the query and never the results (they are
already in the store; copying them into a log doubles the blast radius of a leak for nothing),
and a purge line records that bytes were destroyed and never what they said. Both logs redact a
credential to a length marker. JAMGATE_EVENT_LOG=off turns the event log off. I keep it because it is the corpus the classifier is measured against, and
a future local classifier would need real examples to be any good. It lives beside the store —
gate.log in the same directory as JAMGATE_STORE, or ~/.jamgate/gate.log.
JAMGATE_GATE_LOG overrides the path and JAMGATE_GATE_LOG=off turns it off. It holds the
memory text, so if that bothers you, turn it off. (It follows the store rather than the home
directory so it stays writable under a hardened systemd unit with ProtectHome=true; see
D-037.)
I use this daily, it holds my real memory, and it has not lost a record. That is the strongest claim I can make honestly. It is not battle-tested, because there has only ever been one battle.
What works today: the gate itself (rule pre-filter, credential refusal, exact dedup, topic
resolution and time-aware supersession, the source-trust conflict guard), an archive nothing
can destroy plus restore and a human-only purge, an event log covering every operation, atomic
durable writes with locking, a gated and reversible storage migration, a designed read path
(cross-script lexical bridge, an inverted index, freshness as an ordering tier that never
decides what the reply contains, topic collapse, and a reply that dates and names the topic of
every line) with optional local embeddings on top, the setup wizard for ten clients, and
import --from claude|chatgpt for moving your memory off another product. Optional and less exercised: remote mode over HTTP with a bearer token and
MCP OAuth, a small REST API on the same port, and namespaces. Those last three work and are
tested, but I am the only person who has ever pointed anything at them — the local stdio path
is the one that gets used every day.
701 tests on Node 20 and 22, run against a real MCP handshake on both transports. The full
history is in CHANGELOG.md, and every non-obvious decision, including the
ones I got wrong and reversed, is written up in DECISIONS.md.
The thin classifier for ambiguous cases is now built and measured, but read the row in the table above before you count on it: it is inert on every client that does not implement MCP sampling, which today is nearly all of them.
Next. A review loop: a tool your own agent calls periodically to report the contradictions
no local rule can find, because four rule-based detectors were built, measured against my real
store, and every one of them failed. The design is in
docs/DESIGN-v2.md, and §15 and §15b there list everything building the
foundation and then the read path proved that document wrong about — fifteen items, two of which
were live defects in already-shipped code and one of which was a defect in the instrument doing
the measuring. MIT, and I am not trying to make money from it.
npm install
npm run build # compile TypeScript to dist/
npm test # compile and run the test suite (built-in node:test, no extra deps)
CI runs the build and tests on Node 20.x and 22.x for every push and pull request.
The most useful thing you can do right now is install it and tell me what broke, especially on macOS or Windows, which I have never run. After that: recall ranking, which is the part I'm least happy with.
AGENTS.md gets you oriented and RULES.md has the detail.
Both are written for an AI agent as much as for a person, since most of this was built with
one.
FAQs
A neutral, cross-agent memory quality gate for AI agents, delivered as an MCP server — a gate, not a store.
The npm package jamgate receives a total of 2,613 weekly downloads. As such, jamgate popularity was classified as popular.
We found that jamgate demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Company News
Open source maintainers are under more pressure than ever. We're raising our open source program from the Team plan to the Business plan, free.
Security News
The supply chain control that delays freshly published gems now covers lockfile generation and gem vendoring in Ruby projects.
Security News
During a UK cyber test, a Mythos 5 agent used sockpuppets, social engineering, and prompt injection to try to get a maintainer to merge malware.