KEPTA — the memory for AI systems

KEPTA — 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](https://github.com/DamianTodorovic/kepta/discussions)

flowchart LR

subgraph Apps["Your AI apps — every client, one memory"] direction TB A["Claude Desktop · Claude Code"] B["Cursor · Gemini CLI Cline · Codex · Zed"] C["Your scripts"] end subgraph KEPTA["KEPTA — this repository"] direction TB M["MCP server 8 tools · stdio + Streamable HTTP"] G["HTTP API · 32 routes Python client · CLI"] E["Memory engine hybrid retrieval: FTS5 + vectors + graph RRF fusion → local rerank"] end D[("One encrypted file SQLCipher 4 · AES-256 ~/.kepta/kepta.db")] K["OS keychain 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 # 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:

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 buil