kepta

<p align="center"><img src="public/kepta-logo.svg" width="88" alt="KEPTA"></p>
<h1 align="center">KEPTA — Keeps what matters</h1>
<p align="center"><strong>Your AI assistant forgets you after every chat.<br>KEPTA remembers — on your own computer, in one file.</strong></p>

<p align="center"><sub>Open source · no cloud · no account · no subscription<br>SQLite · hybrid retrieval · knowledge graph · MCP</sub></p>

<p align="center"><strong>English</strong> · <a href="README.de.md">🇩🇪 Deutsch</a></p>

<p align="center"><a href="https://github.com/DamianTodorovic/kepta/releases"><img alt="Release" src="https://img.shields.io/github/v/release/DamianTodorovic/kepta?label=Download"></a> <a href="https://github.com/DamianTodorovic/kepta/actions/workflows/build.yml"><img alt="CI" src="https://github.com/DamianTodorovic/kepta/actions/workflows/build.yml/badge.svg"></a> <a href="https://www.npmjs.com/package/kepta-mcp"><img alt="npm" src="https://img.shields.io/npm/v/kepta-mcp?label=npx%20kepta-mcp"></a> <a href="https://pypi.org/project/kepta/"><img alt="PyPI" src="https://img.shields.io/pypi/v/kepta?label=pip%20install%20kepta"></a> <img alt="Coverage" src="https://img.shields.io/badge/coverage-90%25-brightgreen"> <img alt="Tests" src="https://img.shields.io/badge/tests-1106%20passing-brightgreen"> <a href="LICENSE"><img alt="MIT" src="https://img.shields.io/badge/License-MIT-black"></a> <img alt="Platform" src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey"></p>

## 🎬 The whole app in one pass

<p align="center"><img src="docs/demo.gif" alt="A tour of KEPTA: searching, opening a note in the editor, creating one, moving it to the trash and restoring it, the knowledge graph with its time slider, the chat cockpit, the MCP settings, the command palette and the light/dark switch" width="900"></p>

<sub>A full pass through the app: search, the editor with type and validity, creating a note, the trash with restore, the knowledge graph and its time slider, the chat cockpit, the MCP endpoints, the command palette and the theme switch. Recorded from version 2.6.16 on invented demo data — the Onyx interface.</sub>

| Index & hybrid search | Knowledge graph |
|---|---|
| ![Index](docs/screenshots/01-index.png) | ![Graph](docs/screenshots/03-graph.png) |
| **Editor — type, validity, confidence** | **Setup — topics & starter pack** |
| ![Editor](docs/screenshots/04-editor.png) | ![Setup](docs/screenshots/05-setup.png) |

<sub>Recorded from version 2.6.16 — the Onyx interface — on a demo corpus. No real data: every entry was made up for these shots. Note that the graph was rebuilt in 2.7.0 (unbounded canvas, collision, degree-weighted links); the shot above still shows the old rendering.</sub>

### Knowledge that has a date

<p align="center"><img src="docs/graph-time.gif" alt="The knowledge graph with the time slider: dragging back through time dims every note that did not exist yet at that moment" width="900"></p>

<sub>The time slider answers a question most note apps cannot: <em>what did I know back then?</em> Every memory carries a validity window, so the graph can be replayed. The dimmed nodes are not deleted — they simply were not true yet.</sub>

## 🙋 New here? Start with this

**The problem.** You use ChatGPT, Claude or something similar. You explain your project, your client, the way you like things done. The next day you open a fresh chat and it knows none of it. So you explain it again. And again.

**What KEPTA is.** A small program that runs on your own computer and remembers those things for you. Your assistant can look them up and write new ones back by itself. Nothing is sent anywhere — the notes live in a single file on your machine, like a document.

**What that looks like on an ordinary day.** You tell Claude to remember that your client bills quarterly. Two weeks later, in a brand-new chat, you ask about the invoice and it already knows. You drop a PDF into a folder and your assistant can quote from it. You move house, and the old address stops coming back.

**Is it for you?**

- You use an AI assistant often and keep repeating yourself → yes.
- You want what you tell it to stay on your own machine → yes.
- You are looking for a notes app to read and write by hand → probably not. KEPTA is built so your *assistant* uses it.

### Do I need to be a developer?

**To use the app — no.** Download the file for your system, open it, done. It is an ordinary window: a list, a search box, a settings page. The section [Which file do I need?](#-which-file-do-i-need) tells you exactly which one to take.

**To connect it to Claude Desktop or Cursor — a little.** You paste one short block of text into one configuration file. The block is ready to copy under *Settings → MCP / API*. If you have never edited such a file, this is the single step worth setting aside ten minutes for.

**For the smarter search — optional.** KEPTA searches perfectly well out of the box. Install [Ollama](https://ollama.com) — one free download — and it will additionally find notes that mean the same thing in different words.

<details>
<summary><strong>The words used on this page, in plain terms</strong></summary>

| Word | What it means here |
|---|---|
| **Agent** | An AI program that can use tools instead of only answering — Claude Desktop or Cursor, for instance. |
| **MCP** | An agreed language for such programs to talk to tools. KEPTA speaks it, so those assistants can read and write your notes. |
| **SQLite** | A database that is simply one file on your disk. Nothing to run, nothing to log into; you can copy it like a photo. |
| **Embedding / vector** | Text turned into numbers, so a computer can tell that "car workshop" and "garage" mean nearly the same thing. |
| **BM25 / full text** | Classic keyword search: it finds the words you actually typed. |
| **Knowledge graph** | Your notes linked to one another, like `[[links]]` in a wiki. |
| **RRF** | The formula that merges the three searches above into one ranking. |
| **Local-first** | Everything happens on your machine. No upload, no account, no subscription. |
| **Open source / MIT** | The whole source code is public and free to use. You can read what it does instead of taking my word for it. |

</details>

## 🎯 What it's for

1. **One brain for every AI tool** — Claude Desktop, Cursor and anything else that speaks MCP share the same knowledge base. What one agent learns, the next one already knows.
2. **Keep agents sharp instead of letting them rot** — every memory carries a type, a validity window and a confidence score. Contradictions supersede each other; expired facts are flagged, not silently served.
3. **A second brain** — notes, projects and knowledge found by meaning. Ask *"what do I cook with pasta"* and the carbonara recipe comes back, once `ollama pull nomic-embed-text` has run. Without an embedding model, search stays lexical and still works.
   **Measured caveat, September 2026:** that example works in English and does not work in German. On a four-note check (`npm run embed:sprachtest`) the default model answers 4 of 4 English paraphrase questions and 1 of 4 of the same questions translated into German. The implementation is not at fault — normalised cosine, 768 dimensions — the default model is English-centric. If your notes are German, expect lexical search to carry most of the weight until you switch to a multilingual model such as `bge-m3`.
4. **Capture without friction** — drag in files (PDF/MD/TXT), clip URLs, watch an inbox folder, save chat answers. Or let KEPTA **read the documents already on your computer**: opt-in, with a preview of exactly what would be imported before a single file is opened. Keys, credentials, browser profiles, keychains and system folders are never read, and that cannot be switched off — because an imported note is readable by every agent you connect over MCP.
5. **Obsidian bridge** — vault import and export (Markdown + frontmatter); `[[wiki links]]` become graph edges.
6. **Private** — everything lives in `~/.kepta/`. MIT licensed, no account.
7. **Research** — a knowledge graph that stays legible at thousands of nodes, duplicate review that shows you the pairs instead of just counting them, and a trash can with undo.
8. **Two-minute dev setup** — copy the MCP config, `POST /mcp` (protocol 2026-07-28, 8 tools), HTTP API, `npm run eval` (Hit@1 62 %) and `npm run ablation` (what each retrieval leg contributes).

## 🏗️ How it fits together

```mermaid
flowchart LR
  subgraph Clients["AI clients"]
    CD["Claude Desktop"]
    CU["Cursor"]
    XX["any MCP client"]
  end
  subgraph App["KEPTA — all on your machine"]
    UI["Desktop app<br/>React 19 + Electron"]
    SRV["HTTP server<br/>41 routes"]
    MCP["MCP server<br/>stdio + POST /mcp"]
    ENG["Retrieval engine<br/>one code path for all"]
    ST[("SQLite + FTS5<br/>~/.kepta/kepta.db")]
  end
  OLL["Ollama / LM Studio<br/>optional, local"]
  CD --> MCP
  CU --> MCP
  XX --> MCP
  UI --> SRV
  SRV --> ENG
  MCP --> ENG
  ENG --> ST
  ENG -. embeddings .-> OLL
```

No service in between, no account, no telemetry. The server binds to `127.0.0.1` unless you set `KEPTA_HOST` yourself. Your memories are stored only in that SQLite file — there is no server of mine for them to reach. The one path where data does leave is the app's optional chat: if you enter a key for OpenAI, Anthropic or another provider, what you send that provider goes to them. It is off until you add a key, and the memory store is never synced anywhere.

## 🔍 How search decides

<p align="center"><img src="docs/how-search-decides.gif" alt="One query fans out into BM25 full text, vector KNN and the knowledge graph; the three rankings fuse with RRF, expired and superseded memories are downweighted, and one result surfaces" width="900"></p>

<sub>Real output from an 18-note corpus, not a mock-up. For the query <em>Roman cooking</em> the vector track ranked Cacio e pepe first while full text and