Metadata-Version: 2.4
Name: ktkn-mem
Version: 1.0.0
Summary: Katechon Memory — Sovereign Semantic Memory System
Project-URL: Homepage, https://ktkn.dev
Project-URL: Repository, https://github.com/katechon/ktkn
Project-URL: Documentation, https://ktkn.dev
Author: Katechon Project
License: AGPL-3.0-or-later
License-File: LICENSE
Keywords: embeddings,memory,rag,semantic-search,sqlite,vector-database
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: numpy>=1.24
Requires-Dist: sqlite-vec>=0.1.1
Provides-Extra: coreml
Requires-Dist: coremltools>=7.0; extra == 'coreml'
Requires-Dist: transformers>=4.35; extra == 'coreml'
Provides-Extra: feed
Requires-Dist: feedparser; extra == 'feed'
Requires-Dist: yt-dlp; extra == 'feed'
Provides-Extra: full
Requires-Dist: coremltools>=7.0; extra == 'full'
Requires-Dist: feedparser; extra == 'full'
Requires-Dist: onnxruntime>=1.16; extra == 'full'
Requires-Dist: requests; extra == 'full'
Requires-Dist: tokenizers>=0.15; extra == 'full'
Requires-Dist: transformers>=4.35; extra == 'full'
Requires-Dist: yt-dlp; extra == 'full'
Provides-Extra: mlx
Requires-Dist: mlx-embeddings; extra == 'mlx'
Provides-Extra: onnx
Requires-Dist: onnxruntime>=1.16; extra == 'onnx'
Requires-Dist: tokenizers>=0.15; extra == 'onnx'
Provides-Extra: portable
Requires-Dist: fastembed; extra == 'portable'
Provides-Extra: rag
Requires-Dist: requests; extra == 'rag'
Description-Content-Type: text/markdown

# Katechon Memory (ktkn)

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

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

[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL%203.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)

---

## 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

```bash
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

```bash
# 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`](.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

```bash
# 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](LICENSE) — Use it, modify it, build on it. If you offer it as a hosted service, you must open-source your changes.

---

**[ktkn.dev](https://ktkn.dev)**
