Provides a local, encrypted memory layer for AI clients to store and retrieve knowledge using hybrid search and a knowledge graph.
Also known as DamianTodorovic/kepta, kepta, kepta-mcp
- Stars
- 4
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 3.4.0
- Last commit
- Nov 13, 2026
- License
- —
What is KEPTA MCP?
KEPTA provides a local, encrypted memory layer for AI clients to store and retrieve knowledge using hybrid search and a knowledge graph.
Summary generated from the project's README
About KEPTA MCP server
KEPTA provides a local, encrypted memory layer designed to prevent AI systems from losing context between sessions. It functions as a centralized knowledge base that any MCP client, such as Claude Desktop, Cursor, or Gemini CLI, can read from and write to. By storing information in a single encrypted file on your own computer, it ensures that documents, chat histories, and specific decisions remain accessible regardless of how large a conversation's context window becomes.
The system uses a hybrid retrieval engine combining FTS5, vectors, and a knowledge graph to find information quickly. Developers can interact with the memory through an MCP server with eight specific tools, a local HTTP API with 32 routes, or an embedded Python client. Security is handled via SQLCipher 4 with AES-256 encryption, using the OS keychain to protect the database key on local machines. For containerized or headless environments, the encryption key must be provided through the KEPTA_DB_KEY environment variable.
What you can do with it
- 1Persistent client knowledge storageAn AI client can save specific details about a client's business rules to recall them in future chats.
- 2Migrating existing chat historiesYou can import your previous ChatGPT conversations into your local encrypted memory base.
- 3Cross-client knowledge synchronizationUse the setup command to ensure multiple AI tools like Windsurf and VS Code all access the same memory.
Written from the project's README. Every use case is checked against a quote from it.
How to install KEPTA MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall KEPTA MCP in Claude Code
$ claude mcp add kepta -- npx -y kepta-mcpInstall KEPTA MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"kepta": {
"command": "npx",
"args": [
"-y",
"kepta-mcp"
]
}
}
}Install KEPTA MCP in VS Code
.vscode/mcp.json
{
"servers": {
"kepta": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"kepta-mcp"
]
}
}
}Install KEPTA MCP in VS Code CLI
$ code --add-mcp '{"name":"kepta","type":"stdio","command":"npx","args":["-y","kepta-mcp"]}'Install KEPTA MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"kepta": {
"command": "npx",
"args": [
"-y",
"kepta-mcp"
]
}
}
}Install KEPTA MCP in Codex
$ codex mcp add kepta -- npx -y kepta-mcpInstall KEPTA MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.kepta] command = "npx" args = ["-y", "kepta-mcp"]
Install KEPTA MCP in Gemini CLI
$ gemini mcp add -s user kepta npx -- -y kepta-mcpInstall KEPTA MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"kepta": {
"command": "npx",
"args": [
"-y",
"kepta-mcp"
]
}
}
}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.
Configuration
KEPTA_DB_KEY
Automated checks
Ran Nov 14, 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 · What to fix for more points
- Source repository linked and reachabledamiantodorovic/kepta is public and reachablegithub.com/damiantodorovic/kepta ↗Pass
- Package names this repository as its sourcekepta-mcp names damiantodorovic/kepta as sourcenpmjs.com/package/kepta-mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for kepta-mcpnpmjs.com/package/kepta-mcp/v/3.4.0#provenance ↗Pass
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-10-13github.com/damiantodorovic/kepta ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from kepta-mcpPass
- No critical advisory in the package or its dependencies39 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubKEPTA — the memory for AI systems
Your AI forgets everything. Every chat starts from zero.
KEPTA is the fix: one local, encrypted memory that every AI reads and writes — Claude, Cursor, Gemini CLI, Cline, any MCP client, and scripts over HTTP. No cloud. No account. One file you own.
Everything an AI system learns goes into an encrypted knowledge base on your own computer — and every AI recalls it in milliseconds, however long the context grows. Documents, decisions, client knowledge, whole chat histories: remembered, linked, contradicted, superseded — never lost.
This repository is the source-available core (BUSL-1.1 — every line public, converts to AGPL-3.0-or-later four years after each release): the memory engine, the MCP server, the HTTP API — and the Python client, which is MIT so any Python project can embed it. Everything that makes the memory smart lives in this free engine. There are no tiers inside the memory — nothing is held back to sell anything.
Questions, security feedback or benchmark critique? → Discussions
flowchart LR
subgraph Apps["Your AI apps — every client, one memory"]
direction TB
A["Claude Desktop · Claude Code"]
B["Cursor · Gemini CLI<br/>Cline · Codex · Zed"]
C["Your scripts"]
end
subgraph KEPTA["KEPTA — this repository"]
direction TB
M["MCP server<br/>8 tools · stdio + Streamable HTTP"]
G["HTTP API · 32 routes<br/>Python client · CLI"]
E["Memory engine<br/>hybrid retrieval: FTS5 + vectors + graph<br/>RRF fusion → local rerank"]
end
D[("One encrypted file<br/>SQLCipher 4 · AES-256<br/>~/.kepta/kepta.db")]
K["OS keychain<br/>the key never leaves"]
A --> M
B --> M
C --> G
G --> E
M --> E
E --> D
D -.-> K
⚡ One command, every AI client
Needs Node 22.13 or newer (package.json → engines) on the machine you install on; npm has prebuilt SQLite binaries for Node 22, 24 and 26.
npx -y kepta-mcp demo # six scenes in a throwaway database — nothing of yours is touched
npx -y kepta-mcp setup # connects Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Gemini CLI, Cline and Roo Code
npx -y kepta-mcp remember "Client Miller signs renewals in December." # write a note from the terminal, no AI client needed
npx -y kepta-mcp recall "who signs renewals" # read it back: 1 match — ranked by relevance
npx -y kepta-mcp stats # size, encryption state, top tags
npx -y kepta-mcp timeline "miller" # what was true, and when
npx -y kepta-mcp import chatgpt <export-folder> # bring your ChatGPT history with you (export → extract → import)
What those two lines answer, verbatim — kepta-mcp 3.2.0 from the registry on 10.10.2026, a
throwaway HOME, an empty memory:
$ npx -y kepta-mcp remember "Client Miller signs renewals in December."
✓ remembered — Client Miller signs renewals in December.
type: semantic · id: k-mv2mghs9-fdf75c17
$ npx -y kepta-mcp recall "who signs renewals"
1 match — ranked by relevance
1. Client Miller signs renewals in December. · semantic · today
Client Miller signs renewals in December.
#remember
A note is one thing your memory holds — remember writes one by hand, your AI client writes the same kind through the memory_save tool. Then tell your AI something worth keeping — and watch it arrive. Details in the Quick start.
🖥️ Or download the desktop app
The core has no window of its own: its interface is your AI client. If you want a window, that is the free desktop app — same engine, same encrypted file, same key — and it is downloadable from the releases of this repository. For teams and organizations there is KEPTA Enterprise by agreement. These three sentences are the whole answer; every document here says the same.
The app brings the memory browser, hybrid search with retrieval provenance, the knowledge graph, time travel, dossiers and a chat that reads the memory. Download the DMG for your Mac from the latest release (Apple Silicon or Intel) and drag it into Applications. The build is ad-hoc signed and not notarised, so macOS asks a single time. Two ways through, and both work on every macOS version: xattr -dr com.apple.quarantine /Applications/KEPTA.app, or System Settings → Privacy & Security → the KEPTA message → Open Anyway. Once, then never again. Older guides say right-click → Open; Apple removed that route in macOS 15 and it does nothing on current systems. (What runs from this repository has no window: npm run dev starts the HTTP API and its POST /mcp — a service on your machine, not an interface.)
The app is free, like everything in this repository. KEPTA Enterprise (team and tenant memory, audit chain, human review, point-in-time recovery) is licensed by agreement — write to me on LinkedIn.
🧠 One engine. Free. For every AI.
KEPTA is not a feature inside one app — it is a memory layer that outlives every model, every app and every context window. Three doors lead into the same encrypted file:
| Door | What uses it |
|---|---|
| MCP — 8 tools, stdio (npm binary and container) + Streamable HTTP (this repository, run from source) | Every MCP client: Claude, Cursor, Gemini CLI, Cline, Codex, Zed, your own agents |
| HTTP API — 32 routes, loopback only | Scripts, cron jobs, agent teams, automations |
Python — pip install kepta, standard library only |
Any Python project, embedded |
Free means free: €0, forever — no account, no licence key, no daily limit, no tier inside the memory, nothing locked to sell you later. The best memory engine we can build is the free one; that is the point. This sentence is about money, not about capacity. On one machine the local API stops accepting new notes once KEPTA_MAX_ACTIVE notes are active (5000 by default, server.ts → maxActiveMemories()): a brake on a runaway agent writing your memory full, not a paywall — raise it with that variable and nothing else changes. Nothing in the free core is a locked feature; see SECURITY.md for every such screw.
Teams and organizations — shared team memory, central policies, MDM, organisation-wide audit — get KEPTA Enterprise by request. Coordination is the only thing we ever charge for; memory quality never is. → write to me on LinkedIn
⚡ Quick start
Connect your AI apps
npx -y kepta-mcp setup
Finds Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Gemini CLI, Cline and Roo Code on your computer and adds KEPTA to them. It asks per app (--yes connects all of them), keeps a backup of every file it changes and leaves every other entry alone. Zed, Codex CLI and Continue get the exact snippet to paste (their config formats move too fast to write from outside). Any other MCP client:
{
"mcpServers": {
"kepta": {
"command": "npx",
"args": ["-y", "kepta-mcp"]
}
}
}
8 tools: memory_search, memory_save, memory_update, memory_delete, memory_list, memory_graph, memory_consolidate, memory_forget.
HTTP API
git clone https://github.com/DamianTodorovic/kepta.git
cd kepta && npm install && npm run dev
# → http://127.0.0.1:3000
# save a note
curl -s localhost:3000/api/memory -H 'Content-Type: application/json' \
-d '{"title":"Client Miller","content":"Billed quarterly.","tags":["client"]}'
# search
curl -s "localhost:3000/api/memories/search?q=how+does+miller+pay"
Docker (MCP server only)
Build the image from a clean clone, before any npm install — a node_modules built for macOS that ends up in the build context breaks the Linux build (ERR_DLOPEN_FAILED). Measured on this state, 12.10.2026 (docs/belege/r1/kontext-groesse-2128.log.txt): the same folder carries a 180 MB build context, 169 MB of it node_modules, where the tracked files alone are 4 MB. (.dockerignore now keeps node_modules and build artefacts out of the context; until it reaches your checkout, a clean clone is the safe route.)
git clone https://github.com/DamianTodorovic/kepta.git && cd kepta
docker build -t kepta-mcp .
# A container has no keychain, so the database key is not optional here: it has
# to come from the environment. Generate it ONCE and keep it — it is the only way
# back into the volume.
KEPTA_DB_KEY=$(openssl rand -hex 32)
docker run --rm -i -e KEPTA_DB_KEY="$KEPTA_DB_KEY" -v kepta-data:/data kepta-mcp
No key, no file. Pass a real value: 64 hexadecimal characters, openssl rand -hex 32, generated once and stored where you keep your secrets. A container cannot fall back to a keychain, so without KEPTA_DB_KEY a new knowledge base is not created — KEPTA stops with a non-zero exit and says what to do instead. The same value has to come back on every later start: a fresh openssl rand -hex 32 the second time means a key that does not fit the volume, and that also stops with nothing changed. The only way to a plaintext database is the switch that says so out loud, KEPTA_ENCRYPTION=off.
One transitional sentence for whoever reads this against an older build: before this rule was in the code, an unusable value (a placeholder copied out of a guide, too short, not hex) did not fail — KEPTA printed one line, created the database in plaintext and exited 0. If your kepta.db starts with the bytes SQLite format 3, that is what happened, and the file is readable by anyone who can read it. Check the version, then re-key or replace the volume. SECURITY.md has the whole rule.
CI, servers and every other headless start
A CI runner has no keychain either, so the key comes in as a secret — generated once, not per job, or every run starts a fresh empty memory:
# GitHub Actions, one step. The secret holds the 64 hex characters from `openssl rand -hex 32`.
- run: KEPTA_DB_KEY="${{ secrets.KEPTA_DB_KEY }}" npx -y kepta-mcp stats
Three traps, all measured on this repository:
- An empty value is not "no key".
KEPTA_DB_KEY=""is dropped and the run goes looking in the keychain anyway — on your own machine that means it reads the keychain entry you did not mean to touch. Check that the variable is non-empty before starting, and do not let a templating mistake turn it into"". - A placeholder is a value too. Copying a
<64-hex>-style token out of any guide is the same case as an empty one. - A key in a logged command line is a published key. Pass it through the environment file or the runner's secret mechanism, not through a shell history that CI prints.
If the run cannot reach a key at all, the correct outcome is the one above: no database, a non-zero exit, a sentence naming KEPTA_DB_KEY. A green CI that built a plaintext knowledge base is the failure this rule closes. The full variable list, with defaults and where each is read: docs/ENVIRONMENT.md.
✨ What's inside
| 🔍 Hybrid search | BM25 full text + vector similarity (Ollama) + knowledge graph, fused with RRF, with local reranking. The three legs are not three equal forces — the numbers this repository measures are under the diagram below |
| 🔐 Encrypted at rest | SQLCipher 4: AES-256 and an HMAC-SHA512 over every page, the WAL included; the key lives in the OS keychain (macOS Keychain, Windows DPAPI, Linux Secret Service) |
| 🕐 Time travel | Validity windows (valid_from / valid_to) and asOf queries — "what did I know on 3 March?" |
| ♻️ Superseded, not contradicted | New facts replace old ones (superseded_by); the history stays |
| 🔗 MCP first | 8 tools, one code path for the API and MCP — agents get the same quality as any client |
| 📄 File import | PDF (pdf.js with character maps), Markdown with [[wiki links]], text, JSON |
| 📊 Eval | npm run eval on a fixed corpus of 58 notes / 45 queries: Hit@1, Recall@5 (capped), MRR — lexical only, offline, deterministic. Called recall on purpose: the script divides the hits inside the top five by min(5, relevant) (scripts/eval.ts, in evaluate(): hitsIn5 / Math.min(5, Math.max(1, relevant.length))), which measures how much of the answer set arrived, not how clean the five are. npx tsx scripts/ablation.ts measures each retrieval leg against the others on the same corpus with embeddings from a local Ollama, and its P@5 uses the shared denominator 5 (scripts/ablation.ts:46) — same notes, different metric, numbers not interchangeable |
How a query finds its answer
flowchart TD
Q(["Your query"]) --> A["FTS5 · BM25<br/>lexical search"]
Q --> B["Vector KNN<br/>local embeddings (Ollama)"]
Q --> C["Entity match<br/>knowledge graph"]
A --> R["Reciprocal Rank Fusion<br/>k = 60"]
B --> R
C --> R
R --> BO["Recency + confidence boost"]
BO --> T{"Temporal state?"}
T -->|expired| X5["score × 0.5"]
T -->|superseded| X4["score × 0.4"]
T -->|valid| K1["unchanged"]
X5 & X4 & K1 --> R2["Local reranker<br/>term coverage · phrases · title · tags<br/>max boost +0.25 — no network"]
R2 --> OUT(["Top-k, ranked by relevance"])
What each leg is worth on its own — npx tsx scripts/ablation.ts on this state, 58 notes / 45 queries, local Ollama, measured in three identical runs on 12.10.2026 (docs/belege/r1/ablation-2326.log.txt): Hit@1 with full text alone 71 %, full text + graph 71 % (+0 percentage points), full text + vectors 78 %, all three 76 %; the graph leg alone reaches 11 %. Read that honestly: full text carries the answer, the vector leg is what adds the seven points and is the only leg that needs a model, and on this corpus the graph leg does not raise the ranking — laid on top of the pair it costs two points. It is there for entities and for GET /api/graph, not for the win. Claiming three equal strengths would sell a number the repository's own script contradicts.
🖥️ HTTP API (32 route paths)
32 distinct paths; counting each HTTP verb on its own they are 35 endpoints, because a path like /api/memories, /api/settings and /mcp answers two verbs. Both numbers come from server.ts itself, and tests/doku-zahlen.test.ts counts the paths — so a new verb on an existing path moves only the second number, a new path moves both.
| Area | Routes |
|---|---|
| Memories | GET/POST /api/memories, POST /api/memory, DELETE /api/memories/:id, POST /api/memories/:id/restore, POST /api/memories/bulk-delete, POST /api/memories/bulk-restore, POST /api/memories/reclassify, POST /api/memories/import |
| Search & graph | GET /api/memories/search, POST /api/search, GET /api/graph, GET /api/graph/bild |
| Import / export | POST /api/import/markdown, POST /api/export/markdown |
| Inbox | GET /api/inbox/status, POST /api/inbox/scan |
| Device Sync | POST /api/sync/export, POST /api/sync/import, GET /api/sync/journal |
| Encryption & repair | GET /api/health (including the encryption status), POST /api/repair/imports |
| MCP | POST /mcp, GET /mcp, GET /api/mcp/tools, POST /api/mcp/search, POST /api/mcp/save, POST /api/mcp/consolidate, POST /api/mcp/forget, GET /api/tools, POST /api/embed |
| System | GET /api/settings, PUT /api/settings, GET /api/storage-info, GET /api/activity |
Every route listens on 127.0.0.1 only, with rate limiting, Helmet and input validation.
This API is the server run from this repository (npm run dev, or npm run build && npm start). The published npm binary and the Docker container speak MCP over stdio only — POST /mcp answers here, not from npx kepta-mcp.
Loopback is the default, not a promise: setting KEPTA_HOST binds the same unauthenticated API to that address, and then every machine on the network can read and delete your memory. What to do instead of setting it is written in SECURITY.md.
What the API asks for before it destroys anything
Five behaviours a script has to know, all of them added because the old default was a data loss waiting for a typo:
POST /api/memories/importwithmode:"replace"needsconfirm:"replace". Without it the call answers400and nothing happens — the whole knowledge base used to go with it, permanently, on a one-line call. Before the purge the core writes an encrypted snapshot to<data folder>/backup/kepta-pre-replace-<timestamp>.dband names it asbackupPathin the response.dryRun: trueshowsaffected: { active, trashed }first and changes nothing. A payload that carries no usable note (an empty array, or notes without content) is refused with400— that was the case that erased everything. To restore: put the.dbinto an empty data folder askepta.dband start with the same key. Those snapshots stay where they are, one per confirmed swap — cleaning upbackup/is yours, not the core's.DELETE /api/memories/:id?permanent=is strict. Only1,0,true,false, or the parameter absent (= trash). Anything else,Trueincluded, is a400and deletes nothing;?permanent=1&permanent=0is a400too.GET /api/settingsno longer names secrets. Keys ending inkey,api_key,token,secret,password,passwort,passphrase,schluesseland theai_settingsblob come back as{ gesetzt: true, ende: "…last four characters…" }— under eight characters there is noende, and a deleted entry is gone from the answer. Writing stays onPUT; the full value stays inside the encrypted database. Showgesetzt+endein any UI, never the value.- Error answers are JSON. No stack trace, no absolute paths, no echo of the body you sent.
413names the boundary and what arrived (limitBytes,receivedBytes), a broken body gets a400without repeating itself, and from500up the real reason goes to the server log instead of the response. POST /api/repair/importsaccepts 16 kb. The limit was declared before and never applied (900 KB went through); now anything larger ends in413. Nothing else on this route changed.
Two smaller ones worth a line each: a symlink inside ~/.kepta/inbox/ is not imported — it stays where it is, and POST /api/inbox/scan reports it in skipped: [{ file, reason }] (a link was enough to pull any readable file of yours into the memory an agent sees). And GET /api/graph is capped: up to 500 entities and 2000 relations (src/core/store.ts, getGraph()), with no ORDER BY in front of either cap — which ones come back is decided by row order, not by importance, so a central term can be missing from a big store. One thing those edges do not bring: the relations in the answer carry validFrom and validTo, but the core's own write path leaves both empty (addRelation is called without a window, so the default null stands). A client drawing this graph cannot tell an expired claim from a live one and must not pretend it can.
KEPTA MCP questions
How do I add KEPTA MCP to Claude Code?
Run claude mcp add kepta -- npx -y kepta-mcp in your terminal. Add --scope user to make it available in every project.
How do I add KEPTA MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How does KEPTA handle security and privacy?
KEPTA uses local, encrypted storage via SQLCipher 4 with AES-256 encryption, ensuring your data stays on your machine without any cloud involvement.
Can I use KEPTA in a Docker container?
Yes, but since containers lack access to the OS keychain, you must provide the database key via the KEPTA_DB_KEY environment variable.
Is there a cost to use the memory engine?
The core memory engine and MCP server are free to use with no tiers, accounts, or limits on capacity other than a configurable safety brake.