# ktkn.dev — Katechon Memory

> Sovereign semantic memory for AI agents. Local-first. Zero-ceiling. Yours forever.

## What is Katechon Memory?

Katechon Memory (ktkn) is a hybrid RAG system that gives AI agents persistent, searchable long-term memory using local vector databases. It runs entirely on-device with no cloud dependencies.

The name comes from the Greek "τὸ κατέχον" (to katechon) — "the one who holds fast" — from 2 Thessalonians 2:6-7. It holds what must not be lost.

## Architecture

- `.ktkn` files are self-contained SQLite databases with text chunks + vector embeddings (sqlite-vec)
- `.ktknlib` bundles are directories of related `.ktkn` databases with a manifest.json
- The ANE vector index is like a Dewey Decimal catalog — it finds what you're looking for
- The FTS5 full-text store contains the actual content the catalog points to
- Agent namespaces in `~/.ktkn/agents/{id}/` give each agent its own memory with long-term storage, session logs, and working memory

## Embedding Backends

- CoreML/ANE: Apple Silicon Neural Engine, 925+ chunks/sec, 384-dim (MiniLM-L6-v2)
- ONNX: Cross-platform, works everywhere
- MLX: Apple Silicon GPU
- Ollama: Delegates to running Ollama instance

## CLI Commands

```
ktkn init                    — Set up ~/.ktkn/ with model selection
ktkn search --db X --query Y — Semantic search
ktkn ingest --dir X --db Y   — Ingest files into a database
ktkn rag --db X --query Y    — RAG query (search + synthesize via Ollama)
ktkn lib list                — List mounted libraries
ktkn lib create              — Package databases into a .ktknlib bundle
ktkn lib mount               — Register a library
ktkn agent create ID         — Create an agent memory namespace
ktkn agent list              — List all agents
ktkn agent search ID --query — Search an agent's memory
ktkn profile show            — Show user profile
ktkn migrate                 — Migrate existing databases to .ktknlib format
```

## Agent Integration

Agents don't call `ktkn agent create` — that happens automatically when an agent (like Hermes) chooses ktkn as its memory backend during setup. The agent then:

1. Records conversations verbatim into `sessions.ktkn`
2. Stores key insights in `memory.ktkn`
3. Maintains `working_memory.md` for current context
4. Searches its own memory and mounted libraries

## Key Files

- `ktkn_mem/config.py` — Path resolution (CLI arg → env var → config.json → default)
- `ktkn_mem/cli.py` — CLI entry point with all commands
- `ktkn_mem/store.py` — SQLite + sqlite-vec database operations
- `ktkn_mem/ktkn_mem.py` — Core embedding + search facade
- `ktkn_mem/library.py` — .ktknlib bundle management
- `ktkn_mem/agent.py` — Per-agent memory namespace
- `ktkn_mem/rag.py` — RAG engine (retrieval + Ollama synthesis)
- `ktkn_mem/cross_db_rag.py` — Cross-database RAG with Reciprocal Rank Fusion
- `ktkn_mem/userprofile.py` — LLM-driven user profiling
- `.agents/skills/ktkn-librarian/SKILL.md` — Agent skill for using ktkn

## Install

```
pip install ktkn-mem
ktkn init
```

## Links

- Website: https://ktkn.dev
- Source: https://github.com/anthropic-cookbook/ktkn (placeholder)
- License: AGPL-3.0
