Provides AI agents with persistent, typed memory for decisions, commitments, and facts that survive across different chat sessions.
Also known as B3dmar/3ngram, @3ngram/sdk
- Stars
- 3
- Tools
- —
- Downloads, 30 days
- 3,143
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- Apache-2.0
What is 3ngram MCP?
3ngram provides AI agents with persistent, typed memory for decisions, commitments, and facts that survive across different chat sessions.
Summary generated from the project's README
About 3ngram MCP server
Developers building AI agents that require long-term context can use 3ngram to provide persistent, typed memory across different chat sessions. Unlike standard chat history that flattens into a single stream, this system categorizes information into specific types like decisions, commitments, blockers, and facts. This allows agents using Claude, ChatGPT, or Cursor to maintain a structured understanding of project states and user preferences that survives after a conversation ends.
Users can deploy the system via a managed cloud endpoint or self-host the entire stack using Docker Compose with Postgres, pgvector, and Redis. The server provides 11 MCP tools, including remember, search, and get_facts, to manage the lifecycle of information. It uses an append-and-supersede model where corrections create connections between memories rather than deleting old data, ensuring that historical records remain queryable through bi-temporal tracking.
To ensure accuracy, the system includes a review process for background tasks. Through the review_proposals tool, users can manually approve or reject suggestions made by the server regarding duplicate memories, completed commitments, or archived notes. This human-in-the-loop approach prevents the AI from silently altering its own knowledge base.
What you can do with it
- 1Maintain project continuityAsk an AI agent to retrieve specific project decisions made in previous sessions to ensure consistency.
- 2Audit historical knowledgeQuery the system to understand what the agent believed about a specific topic at a certain point in time.
- 3Verify automated memory updatesReview and approve suggested changes to the memory database to prevent incorrect data from being saved.
- 4Track evolving truthsDistinguish between what is currently true and what was previously recorded as a fact.
Written from the project's README. Every use case is checked against a quote from it.
How to install 3ngram MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall 3ngram MCP in Claude Code
$ claude mcp add 3ngram -- npx -y 3ngramInstall 3ngram MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"3ngram": {
"command": "npx",
"args": [
"-y",
"3ngram"
]
}
}
}Install 3ngram MCP in VS Code
.vscode/mcp.json
{
"servers": {
"3ngram": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"3ngram"
]
}
}
}Install 3ngram MCP in VS Code CLI
$ code --add-mcp '{"name":"3ngram","type":"stdio","command":"npx","args":["-y","3ngram"]}'Install 3ngram MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"3ngram": {
"command": "npx",
"args": [
"-y",
"3ngram"
]
}
}
}Install 3ngram MCP in Codex
$ codex mcp add 3ngram -- npx -y 3ngramInstall 3ngram MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.3ngram] command = "npx" args = ["-y", "3ngram"]
Install 3ngram MCP in Gemini CLI
$ gemini mcp add -s user 3ngram npx -- -y 3ngramInstall 3ngram MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"3ngram": {
"command": "npx",
"args": [
"-y",
"3ngram"
]
}
}
}Needs a key before it starts
Started on 16 Nov 2026 with no keys, it stopped and asked for one, so a client sees no tools until you set the variables above.
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubPersistent, typed memory for AI agents
Decisions, commitments, blockers, and facts that survive the session, across Claude, ChatGPT, Cursor, and your own agents. MCP-first, self-hostable backend, Apache-2.0.
Documentation · Quickstart · Self-host · Benchmarks · Contributing
3ngram gives your AI tools a memory that outlives the conversation. Memories are typed: decisions, commitments, blockers, facts, preferences, patterns, notes, and events each keep their own lifecycle, instead of everything flattening into chat history. They are searchable from any connected client, stored in Postgres with pgvector, and never silently rewritten.
- Append-and-supersede. Writes never destroy data. Corrections create typed edges between memories, so the old record stays queryable, including "what did I believe on date X".
- Bi-temporal facts. Facts track both when they were true in the world and when the system learned them, so retrieval can answer "what is true now" and "what was true then".
- Knows what it doesn't know. Retrieval is calibrated to abstain rather than return a confident false match when the answer genuinely isn't stored.
- A deliberately small surface. 11 MCP tools and 2 prompts over Streamable HTTP, mirrored on a REST API (
/api/v1), designed around jobs to be done, not feature count.
Approve before it lands
Some of 3ngram's background work ends in a proposal instead of a change. Every hour, the consolidation pass proposes an edge between two memories that look like near-duplicates. Where the opt-in judgment passes are turned on, the session closer proposes resolving a commitment it thinks is done but is not sure about, and the forgetting pass proposes archiving or superseding a memory it thinks is finished.
A proposal changes nothing until you accept it: search ranks as before, get_facts returns the same facts, and the commitment is not resolved. You list, accept or reject proposals with the review_proposals tool. It is an ordinary MCP tool, so you can review from any connected client, such as Claude, ChatGPT or Cursor. Each kind, and what accept and reject do: Approve before it lands.
How to run it
| Tier | How | Best for |
|---|---|---|
| Self-hosted | docker compose -f compose.selfhost.yml up |
Full control on your own infrastructure: stock Postgres + pgvector and Redis, no maintainer access, no phone-home. Apache-2.0. |
| Library | The @3ngram/* packages (core, server, schema, and more) publish to public npm under Apache-2.0 |
Building on the memory core, or running the server, inside your own toolchain. |
| Cloud | Managed MCP endpoint at 3ngram.ai | A zero-ops hosted option. See the quickstart to connect a client. |
Everything needed to run the 3ngram memory backend yourself is in this repository. The hosted dashboard and cloud-operations code are proprietary and maintained in a separate private repository; neither is required to use the MCP server, REST API, SDK, or CLI. The REST, authentication, onboarding, and profile routes used by the hosted dashboard remain part of this Apache-licensed server and can be used by other clients.
Quickstart (self-host)
Stand up the core (MCP server, REST API, Postgres with pgvector, and Redis) with Docker Compose:
git clone https://github.com/B3dmar/3ngram && cd 3ngram
cp .env.selfhost.example .env.selfhost # set the required secrets (documented inline)
# migrate the schema and provision the runtime role, then start the stack
docker compose --env-file .env.selfhost -f compose.selfhost.yml run --rm migrations
docker compose --env-file .env.selfhost -f compose.selfhost.yml up -d
A fail-closed preflight refuses to boot on blank or placeholder secrets. The server exposes /health and the REST API on port 3000. Seed a golden dataset and mint a demo API key (3ng_<prefix>_<secret>) with pnpm seed; the full walkthrough is in Self-host.
Before running a search, configure both LLM_GATEWAY_URL and LLM_GATEWAY_API_KEY in .env.selfhost and restart the server. Seeded memories include cached vectors, but the server still needs an embedding provider to embed each query; without one, search returns 503 embedding_unavailable. Writes still succeed without a gateway, but the memory is stored with a NULL embedding and is not queued for automatic backfill — configuring a provider later embeds only subsequent writes, so set the gateway before writing any memory you expect to reach via vector search.
Published container
The official multi-platform server image supports Linux amd64 and arm64:
docker pull ghcr.io/b3dmar/3ngram:latest
Pin a specific release instead of latest with its full version tag, e.g. docker pull ghcr.io/b3dmar/3ngram:1.0.2.
Each release also publishes the major/minor (e.g. 1.0) and sha-<full-git-sha> tags, an
SBOM, build provenance, and a GitHub-signed attestation. For immutable digest
pulls and verification, see the container image guide.
First memory operation
With a running server and an API key, write and search a memory over REST:
# remember a typed decision
curl -X POST http://localhost:3000/api/v1/memories \
-H "X-API-Key: 3ng_<prefix>_<secret>" \
-H "Content-Type: application/json" \
-d '{
"memoryType": "decision",
"topic": "search backend",
"content": "Use Postgres full-text search for v1.",
"scope": "work",
"project": "3ngram"
}'
# search it back: requires the embedding provider configured above
curl -X POST http://localhost:3000/api/v1/search \
-H "X-API-Key: 3ng_<prefix>_<secret>" \
-H "Content-Type: application/json" \
-d '{ "query": "what did we decide about the search backend?" }'
Connect an MCP client
3ngram is MCP-first. Point an OAuth-capable client at the local server's /mcp endpoint:
claude mcp add --transport http 3ngram-local http://localhost:3000/mcp
For the managed service, use https://mcp.3ngram.ai/mcp instead. Then ask your client to remember something and search it back in a later session. The quickstart guide covers each client and the OAuth flow.
Typed TypeScript client
@3ngram/sdk is a published, thin typed client over the REST /api/v1 surface:
npm install @3ngram/sdk
import { ThreengramClient } from '@3ngram/sdk'
const client = new ThreengramClient({
baseUrl: 'http://localhost:3000',
apiKey: process.env.THREENGRAM_API_KEY!,
})
await client.remember({
memoryType: 'decision',
topic: 'search backend',
content: 'Use Postgres full-text search for v1.',
scope: 'work',
project: '3ngram',
})
const results = await client.search('what did we decide about the search backend?')
The surface
| Job | Tool |
|---|---|
| Persist something worth keeping | remember |
| Find what you know | search |
| Correct the record | revise, resolve |
| Start a session oriented | briefing |
| Carry context to another agent | handoff |
| What is currently true about X | get_facts |
| Organize your memory space | configure_scope |
| Approve what background work proposed | review_proposals |
| Inspect capabilities and config | describe_environment |
Full schemas: MCP tools · REST API · CLI · SDK.
Benchmarks as the goal function
Retrieval quality is invisible to code review, so 3ngram treats its benchmark as a merge gate: a deterministic golden-set eval runs in CI on every change, and a PR that regresses it does not merge. The recorded floors only ratchet upward.
| Metric | Floor |
|---|---|
| recall@5 | 0.9773 |
| MRR@5 | 0.9697 |
| Supersession correctness | 0.9474 |
| Abstention precision | 1.0000 |
Measured over 98 queries across 158 anonymized production memories, including real supersession chains. Supersession is scored with superseded rows still in the index (it proves ranking, not filtering), and abstention on topics that are verifiably absent. Methodology and reproduction: Benchmarks · eval/.
How it's built
TypeScript monorepo (Turborepo) · Zod v4 · Drizzle · Express · the official MCP TypeScript SDK · BullMQ · Postgres 18 + pgvector · Redis. Self-host runs the same code on vanilla Postgres + Redis.
The design is documented decision-first in the Concepts docs:
- Architecture and Memory model: append-and-supersede, typed memories, bi-temporal facts
- Data model and MCP server design: schema, row-level security, and the tool contract
AGENTS.md: repo rules, commands, and workflow for contributors and AI assistants
Contributing
Contributions are welcome. See CONTRIBUTING.md for the workflow (DCO sign-off required), SUPPORT.md for where to ask questions, and SECURITY.md for reporting vulnerabilities. All participation is covered by the Code of Conduct.
License
Apache-2.0 for every file in this repository, permanently: the memory engine, MCP server, REST API, SDK, and CLI are all open source and self-hostable. The hosted dashboard and cloud-operations code are proprietary and maintained in a separate private repository; neither is needed to run the 3ngram memory backend. Details: LICENSING.md.
3ngram MCP questions
How do I add 3ngram MCP to Claude Code?
Run claude mcp add 3ngram -- npx -y 3ngram in your terminal. Add --scope user to make it available in every project.
How do I add 3ngram MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How can I run 3ngram myself?
You can self-host the backend using Docker Compose with Postgres, pgvector, and Redis.
Does 3ngram overwrite old memories when I make a correction?
No, it uses an append-and-supersede model where corrections create typed edges so old records remain queryable.
Can I review proposed changes to my memory?
Yes, you can use the review_proposals tool to list, accept, or reject proposals for merging near-duplicate memories or archiving finished ones.
What happens if I don't configure an embedding provider?
Writes will still succeed, but the memory will be stored with a NULL embedding and will not be searchable via vector search.