ktkn-mem 1.0.0

Katechon Memory — Sovereign Semantic Memory System

Katechon Memory (ktkn)

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

τὸ κατέχον — "the one who holds fast"

---

What is ktkn?

Katechon Memory is a hybrid RAG engine that gives AI agents persistent, searchable long-term memory. It runs entirely on your machine — no cloud, no API keys, no data leaving your device.

Think of it as a personal library system:

• The vector index is the Dewey Decimal catalog — it finds what you're looking for
• The full-text store holds the actual books
• The Librarian (agent skill) knows how to use both
• Agents are scholars who get library cards and build their own collections

Quick Start

pip install ktkn-mem
ktkn init

ktkn init detects your platform, finds existing embedding models (Ollama, LM Studio, HuggingFace), and lets you choose a backend:

• CoreML/ANE — 925+ chunks/sec on Apple Silicon (recommended for Mac)
• ONNX — cross-platform, works everywhere
• Ollama — uses your existing Ollama installation

Usage

# Search a database
ktkn search --db archive.ktkn --query "Byzantine theology"

# Ingest files into a new database
ktkn ingest --dir ./documents --db mylib.ktkn

# RAG query (search + synthesize via Ollama)
ktkn rag --db archive.ktkn --query "What are my ideas about governance?"

# Cross-database RAG with Reciprocal Rank Fusion
ktkn rag --db-dir ./libraries/ --query "the restrainer" --sources --report

# Library management
ktkn lib list                     # See mounted libraries
ktkn lib create --name "research" --source ./ktkns/ --output research.ktknlib
ktkn lib mount ./research.ktknlib

# Agent memory (created automatically when agents connect)
ktkn agent list                   # See registered agents
ktkn agent info hermes-v1         # Agent memory stats

# User profiling
ktkn profile show                 # View your profile
ktkn profile update               # Analyze conversations, build profile

For Agent Developers

ktkn is designed to be a memory backend that agents plug into. When an agent (like Hermes) chooses ktkn during setup:

1. A namespace is created at ~/.ktkn/agents/{agent-id}/
2. The agent records conversations verbatim into sessions.ktkn
3. Key insights go into memory.ktkn
4. Current context lives in working_memory.md
5. The agent can search its own memory + any mounted libraries

See .agents/skills/ktkn-librarian/SKILL.md for the full agent integration guide.

Architecture

Component	What it does
.ktkn file	Self-contained SQLite database with text chunks + vector embeddings
.ktknlib bundle	Directory of related .ktkn databases with a manifest
ktkn CLI	System-wide command-line interface
kTkN-MCP	Swift-based ANE embedding server for sandboxed agents
Librarian Skill	Teaches any agent how to use the library system

~/.ktkn/
├── config.json           # Global configuration
├── models/               # Embedding models
├── libraries/            # Mounted .ktknlib bundles
├── agents/               # Per-agent memory namespaces
│   ├── _system/          # System agent (librarian, user profiler)
│   └── hermes-v1/        # Agent-managed namespace
└── feeds/                # Feed configurations (RSS, YouTube, Apple Docs)

Install Options

# Python CLI (all platforms)
pip install ktkn-mem              # Core
pip install ktkn-mem[onnx]        # + ONNX runtime
pip install ktkn-mem[full]        # Everything

# System-wide (no venv needed)
pipx install ktkn-mem

# From source
git clone https://github.com/anthropic-cookbook/ktkn
cd ktkn && pip install -e ".[full]"

# MCP Server (macOS, Apple Silicon)
swift build -c release    # from kTkN-MCP-Server/

License

AGPL-3.0 — Use it, modify it, build on it. If you offer it as a hosted service, you must open-source your changes.

---

ktkn.dev