KEPTA — the memory for AI systems

KEPTA Core

Your AI assistant forgets everything. Every chat starts from zero.

KEPTA is the fix: one local, encrypted memory that every assistant reads and writes — Claude Desktop, Cursor, Gemini CLI, Cline, any MCP client, and scripts over HTTP. No cloud. No account. One file you own.

KEPTA is a local memory for AI assistants. Documents, decisions and client knowledge go into an encrypted knowledge base on your own computer — and your assistant (Claude Desktop, Cursor, any MCP client) recalls it as if it had never forgotten.

This repository is the open core (AGPL-3.0): the memory engine, the MCP server, the HTTP API — and the Python client, which is MIT so any Python project can embed it. The full desktop application is KEPTA Pro.

flowchart LR
  subgraph Apps["Your AI apps — any of them"]
    A["Claude Desktop"]
    B["Cursor · Gemini CLI<br/>Cline · Codex · Zed · …"]
    C["Your scripts"]
  end
  K["keptа-mcp<br/>MCP stdio + browser UI"]
  E[("KEPTA — one encrypted file<br/>SQLCipher 4 · ~/.kepta/kepta.db")]
  A & B & C --> K --> E

---

⚡ See it first, connect it second

The desktop app first: Download KEPTA Pro — every download starts with one free Pro day (24 hours, every tool, unlimited, no card, no account, no key), then it runs free with daily limits and never locks.

Or headless, right in your agents:

npx -y kepta-mcp setup   # connects Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Gemini CLI, Cline and Roo Code
npx -y kepta-mcp ui      # your real memory in the browser — watch your AI use it, live
npx -y kepta import chatgpt <export-folder>   # bring your ChatGPT history with you (export → extract → import)
npx -y kepta-mcp stats        # the terminal experience: remember, recall, timeline, contradict

Then tell your AI something worth keeping — and watch it arrive. Details in the Quick start.

---

🚀 KEPTA — one engine, three tiers

KEPTA is one product family around one engine. The engine in this repository is what your agents talk to — free and open source, forever. The desktop app, KEPTA Pro, is what you work in. Teams and organizations get the same app with more control on top.

Tier	For	Price	What it includes
Core	Developers & AI agents	€0, open source, forever	This repository: the memory engine, encryption, hybrid search, MCP, HTTP API, Python client, CLI, browser UI with a read-only knowledge graph, ChatGPT import
Pro	Individuals & power users	€12/month or €120/year, self-serve in the app — every download starts with one free Pro day	The desktop experience on the same engine: knowledge graph, chat with your memory, dossiers, Today, privacy shield, imports, device sync
Enterprise	Teams, practices & organizations	By agreement	Everything in Pro, plus team memory (shared knowledge, workspaces, roles, admin console), SSO, central policies, MDM/air-gapped deployment, security documentation and support

Core is never crippled to sell Pro — the best memory engine we can build is the free one. What we sell is how you use it.

KEPTA Pro — the full desktop app

A native app for macOS and Windows that turns the same encrypted knowledge base into a second brain you can see, search, shape and trust — every document, every decision, every connection, on your own machine.

Today — what changed since your last visit, and what needs a look	Activity — which AI app reads and writes what, live
Privacy shield — what a cloud AI would get to see	The knowledge graph — every note a node, every link an edge

_{KEPTA Pro 2.13 on an invented demo corpus — nothing in these shots is real. Claude and Cursor worked on it through the MCP server of this repository.}

Every feature, side by side. ✅ available · API / MCP in the core for agents and scripts, without a screen for it · — only in KEPTA Pro

Feature	KEPTA Core	KEPTA Pro
Security & privacy
Encrypted at rest — SQLCipher 4, AES-256 and an HMAC-SHA512 over every page, the WAL included	✅	✅
The key is created and kept in the OS keychain automatically — nothing to type, agents never see it	✅	✅
Recovery key in one click, ready for your password manager	✅	✅
Settings — the AI key included — live inside the encrypted file	✅	✅
Loopback only (127.0.0.1), no account, no telemetry — nothing leaves your machine unless you pick a cloud AI	✅	✅
Rate limiting, Helmet and input validation on every route	✅	✅
Hardened desktop shell — no Node in the window, sandbox, Content Security Policy	—	✅
Notes
Create, edit, delete — trash with restore	✅	✅
Four kinds of knowledge — fact, event, how-to, document — assigned by readable rules that state their reason	✅	✅
Sort existing notes by kind afterwards, with a preview first	✅	✅
Tags, confidence 0–1, automatically extracted entities	✅	✅
Scopes — user, agent, session — so a memory knows whom it belongs to	API · MCP	API · MCP
Validity windows — expired notes are marked, never quietly hidden	✅	✅
Supersede chains — a new fact displaces the old one, the history stays	✅	✅
Migration from the old memories.json — idempotent, with a backup	✅	✅
Search
Hybrid retrieval — BM25 full text + vectors + entities, fused with Reciprocal Rank Fusion	✅	✅
Local reranking — term coverage, phrases, title, tags; no network	✅	✅
Relevance first — results ranked, the best hit on top	✅	✅
Time-travel search — what was known at any moment (asOf)	API · MCP	API · MCP
Persistent embeddings via Ollama, computed by a background queue	✅	✅
Temporal weighting — expired ×0.5, superseded ×0.4	✅	✅
Stopwords in German and English	✅	✅
Semantic search switch and a result slider from 5 to all	—	✅
One code path for interface, HTTP API and MCP — agents get the quality you get	✅	✅
Retrieval eval — npm run eval measures Hit@1, Precision@5 and MRR	✅	✅
Capture & import
Drag & drop files — PDF with the character maps of embedded fonts, Markdown, text, JSON — chunked	—	✅
Inbox folder, watched and imported automatically	API	✅
Obsidian vault import — frontmatter kept, [[wiki links]] become graph edges	API	✅
JSON import of whole note sets	API	✅
Re-read files imported with an older extraction — counts first, writes after you confirm	API	✅
URL clipper — SSRF-protected, strips navigation lines and cookie banners	—	✅
Scan this computer — opt-in, preview first; keys, credentials, browser profiles and wallets stay blocked	—	✅
Auto-learn — save the key point of a chat answer (off by default)	—	✅
Markdown export to a folder	API	✅
Device Sync — move a scope between your own devices as an AES-256-GCM bundle, with a hash-chained ledger	API	✅
Knowledge graph
Entities and relations from [[wiki links]] and automatic extraction	API · MCP	✅
Read-only knowledge graph — notes as nodes, [[links]] as edges (solid), similar notes connected (dashed), drag and click	✅	—
Terminal experience — remember, recall, timeline, contradict, stats on the encrypted database	✅	✅ (desktop app)
Interactive graph with two views — Force (physics) and Tree (dendrogram); nodes glide between them	—	✅
Unbounded canvas — 3 000 nodes and 9 500 edges at 60 fps; zoom, pan, drag, fit-to-view	—	✅
Time slider — the graph as it stood on any day	—	✅
Colour by kind, size by connections, real links told apart from mere similarity; double-click opens the note	—	✅
Maintenance
Duplicate detection — embedding similarity ≥ 0.92, lexical fallback without Ollama	MCP	✅
Consolidation supersedes instead of deleting — nothing is lost	MCP	✅
Duplicate review — groups side by side, keep the richest copy in one click, one undo for the batch	—	✅
Episodic memories grow out of chat history	—	✅
Activity feed	✅ live, with the name of the AI app	✅
Agents (MCP)
MCP 2026-07-28, compatible with 2025-06-18 and 2024-11-05 — stdio and Streamable HTTP	✅	✅
Eight tools — search, save, update, delete, list, graph, consolidate, forget — with outputSchema and structuredContent	✅	✅
Write gate (opt-in) — a local LLM decides ADD, UPDATE, DELETE or NOOP before a new memory is stored	✅	✅
npm package kepta-mcp, listed in the official MCP registry	✅	✅
Connect Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Gemini CLI, Cline and Roo Code in one step — npx kepta-mcp setup or one click	✅	MCP block to copy
Python client — pip install kepta, standard library only	✅	✅
Chat cockpit
20 provider presets — Ollama, LM Studio, OpenAI, Anthropic, Gemini, Mistral, Groq, DeepSeek, xAI and more	—	✅
Model discovery for Ollama and LM Studio in one click	—	✅
Streaming with a stop button, Markdown rendering	—	✅
Source citations — every answer shows which memories it used	—	✅
Date-aware prompting and a visible token budget	—	✅
Interface
An interface for your memory — browse by kind and tag, search, read, write, trash	✅ in your browser	✅ native app
Native desktop app for macOS and Windows	—	✅
Light and dark	✅	✅
Keyboard first — shortcuts; in Pro also a command palette (⌘K)	✅	✅
Tag filter with counts	✅	✅
Knowledge list with readable titles and previews	✅	✅
Source chips, part badges, Open file, grouping by file, kind or period	—	✅
Focus mode and text size (100 / 115 / 130 %)	—	✅
Setup assistant with a starter pack	—	✅
System status — detects local AI, checks storage, shows diagnostics	—	✅
Price
License	free · AGPL-3.0	proprietary · free plan with daily limits, Pro removes them

KEPTA Pro never locks — and it never phones home. The app runs as a free plan with generous daily limits on the Pro tools — and a license key removes them, validated offline on your machine: no account, no internet, no trial timer. Pro is 12 €/month or 120 €/year, bought from inside the app — the Upgrade button always points to the current way to buy (while the self-serve checkout is in its final review, that is a direct line to me on LinkedIn); Enterprise — team memory, SSO, MDM, security documentation — is shaped personally. The installers are at kepta-pro-releases.

---

⚡ 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.

Your memory in the browser

npx -y kepta-mcp ui

Opens KEPTA Core in your browser on http://127.0.0.1:4747 — the same encrypted knowledge base your agents write to, now one click away. Browse by kind and tag, search ranked by relevance, open a note and follow its [[links]], write and edit notes with their kind, tags and validity, move them to the trash and bring them back, dark or light. And watch your AI apps at work: which one saved, updated or looked up what — live, while you talk to it. Nothing to install, nothing leaves your machine, and only your own browser tab can change anything. --port picks another port, --no-open keeps the browser closed.

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)

docker build -t kepta-mcp .
docker run -i -e KEPTA_DB_KEY=<64-hex> -v kepta-data:/data kepta-mcp

---

✨ What's inside

🔍 Hybrid search	BM25 full text + vector similarity (Ollama) + knowledge graph, fused with RRF, with local reranking
🔐 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 the app
📄 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, Precision@5, MRR, plus an ablation test per retrieval leg

---

🖥️ HTTP API (29 routes)

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
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, 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.

---

🐍 Python client

pip install kepta

from kepta import KeptaClient
kepta = KeptaClient()
kepta.save("Carbonara", "Guanciale, pecorino, egg yolk. No cream.", tags=["cooking"])
for hit in kepta.search("carbonara without cream"):
    print(f"{hit.score:.2f}  {hit.memory.title}")

No dependencies — only the Python standard library.

---

🏗️ Architecture

src/core/           memory engine (store, search, encryption, MCP protocol)
server.ts           HTTP API (Express, 29 routes)
src/mcp-server.ts   MCP stdio server (npx kepta-mcp) and the browser interface (npx kepta-mcp ui)
src/ui/             the interface: a small local server and one page, no framework, no CDN
npm/                source of the npm package (kepta-mcp)
Dockerfile          container for the MCP server
python/             Python client (PyPI: kepta)
scripts/            eval, benchmark, repair
tests/              Vitest suite with CI-enforced coverage thresholds

One code path for the HTTP API and the MCP server — agents get the same results as direct API calls.

---

🔐 Encryption

The knowledge base is a SQLCipher 4 database: AES-256, an HMAC-SHA512 over every page, the WAL included. The key — 256 random bits — lives in the operating system's keychain: the macOS Keychain, Windows DPAPI or the Linux Secret Service. On servers without a keychain, set KEPTA_DB_KEY to 64 hexadecimal characters. What it covers, what it does not, and how to keep a copy of the key: SECURITY.md.

---

🧪 Quality

437 tests with Vitest and v8 coverage. The coverage thresholds are a CI gate: a commit that falls below one of them turns CI red. On top: a retrieval eval (Hit@1, Precision@5, MRR) on a fixed corpus, an ablation test per retrieval leg, an encryption eval and a boundary test on the core architecture.

Coverage thresholds (enforced by CI)

Area	Lines	Functions	Branches	Statements
everything together	70 %	72 %	56 %	66 %
src/core	87 %	89 %	74 %	85 %

---

👋 Who builds KEPTA

KEPTA is built by Damian Todorovic. Questions, ideas, a license for your team — or you simply want to follow where this is going: find me on LinkedIn.

📄 License

AGPL-3.0-or-later. KEPTA Pro (€12/month, €120/year, self-serve in the app — every download starts with one free Pro day, then the app runs free with daily limits and never locks — the limits are sealed against restarts, clock tricks and even wiping the database (App 2.13.7)) is the desktop app on top of this engine — the knowledge graph, the chat, the machine scan, the privacy shield, the audit log and the polished experience. KEPTA Enterprise is licensed by agreement: everything in Pro, plus team memory for practices and firms, SSO, MDM and security documentation, shaped to your organization. The npm package kepta-mcp carries the same AGPL as this repository; the Python client under python/ is MIT. Licenses and questions — write to me on LinkedIn.

What this repository is — and what it is not. This open core is the memory engine: storage, retrieval, MCP. The product people pay for is the app on top — and it stays proprietary on purpose. Forks under AGPL are legitimate; presenting a fork as KEPTA is not: the KEPTA name, the KEPTA branding and the KEPTA Pro releases belong to Damian Todorovic. Fork it, build with it, ship your own product from it — under a different name, with the AGPL obligations intact (your changes stay open, including over a network). Private notes never leave KEPTA over MCP, in the app and in this core alike.

---