ktkn-mem 1.0.0__tar.gz

ktkn_mem-1.0.0/.agents/skills/ktkn-librarian/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: ktkn-librarian
+description: >
+  Interact with Katechon Memory (ktkn) — the sovereign semantic memory system.
+  Use this skill whenever you need to search a knowledge base, store memories,
+  manage an agent's memory namespace, or retrieve context from past conversations.
+  Trigger on: 'search memory', 'remember', 'store this', 'ktkn', 'katechon',
+  'my notes', 'my conversations', 'what did I say about', 'find in my archive',
+  'library', '.ktkn', 'memory layer', 'semantic search', 'RAG query'.
+---
+
+# Katechon Memory — Agent Skill (The Librarian)
+
+You are interacting with **Katechon Memory (ktkn)**, a local-first sovereign semantic memory system. Think of it as a library system:
+
+| Library Concept | Katechon Equivalent |
+|----------------|---------------------|
+| **Dewey Decimal Catalog** | ANE vector index (sqlite-vec) — finds what you're looking for |
+| **The Books** | FTS5 full-text store — the actual content the catalog points to |
+| **The Librarian** | This skill — you, knowing how to use the catalog and retrieve books |
+| **Library Card** | Your agent namespace in `~/.ktkn/agents/{your-id}/` |
+
+## Prerequisites
+
+The `ktkn` CLI must be installed. Verify with:
+```bash
+ktkn --help
+```
+
+If not available, the user needs to install it:
+```bash
+pip install ktkn-mem       # or: pipx install ktkn-mem
+ktkn init                  # creates ~/.ktkn/ structure
+```
+
+## System Layout
+
+```
+~/.ktkn/
+├── config.json           # Global configuration
+├── models/               # Embedding model files
+├── libraries/            # Registered .ktknlib library bundles
+│   └── mounts.json       # {"name": "/path/to/library.ktknlib"}
+├── agents/               # Per-agent memory namespaces
+│   ├── _system/          # System agent (librarian, user profiler)
+│   │   ├── agent.json
+│   │   └── userprofile.ktkn
+│   ├── hermes-v1/        # Example agent
+│   │   ├── agent.json
+│   │   ├── memory.ktkn   # Long-term semantic memory
+│   │   ├── sessions.ktkn # Conversation history
+│   │   └── working_memory.md
+│   └── ...
+└── feeds/                # Feed configurations (RSS, YouTube, Apple Docs)
+```
+
+## Core Operations
+
+### 1. Search a Database
+
+Search for semantically similar content in a specific `.ktkn` database:
+
+```bash
+ktkn search --db /path/to/database.ktkn --query "your search terms" --top-k 10
+```
+
+**Example — Search the Gutenberg literature corpus:**
+```bash
+ktkn search --db ~/.ktkn/libraries/gutenberg.ktknlib/literature.ktkn \
+  --query "the nature of justice and law" --top-k 5
+```
+
+### 2. List Available Libraries
+
+See what knowledge stores are registered:
+
+```bash
+ktkn lib list
+```
+
+Output shows library name, database count, total chunks, size, and embedding model.
+
+### 3. Get Library Details
+
+```bash
+ktkn lib info /path/to/library.ktknlib
+```
+
+### 4. RAG Query (Search + Synthesis)
+
+Ask a question and get a synthesized answer from the archive. Requires Ollama running:
+
+```bash
+# Single database RAG
+ktkn rag --db /path/to/archive.ktkn --query "What are the user's views on governance?" \
+  --model granite4:micro-h --sources
+
+# Cross-database RAG (searches all .ktkn files in directory)
+ktkn rag --db-dir /path/to/ktkn.ktkns/ --query "Byzantine influence on Western theology" \
+  --model granite4:micro-h --sources --report
+```
+
+**RAG modes:**
+- Default: Question → Answer with citations
+- `--report`: Structured markdown report with synthesis
+- `--deep`: Focus on finding the USER's original ideas (not AI responses)
+- `--stream`: Stream the output token by token
+
+### 5. Agent Memory Operations
+
+#### Create your agent namespace (if you don't have one yet):
+```bash
+ktkn agent create {your-agent-id} --display-name "Your Name"
+```
+
+#### List all agents:
+```bash
+ktkn agent list
+```
+
+#### Store a memory:
+Use the Python API (from within your agent code):
+```python
+from ktkn_mem.agent import AgentMemory
+
+agent = AgentMemory("your-agent-id")
+agent.store_memory(
+    text="The user prefers local-first solutions over cloud dependencies.",
+    tags="preference,architecture",
+    source="conversation-2026-06-23"
+)
+```
+
+#### Search your own memories:
+```bash
+ktkn agent search {your-agent-id} --query "user preferences" --top-k 5
+```
+
+#### Read/update working memory:
+```python
+from ktkn_mem.agent import AgentMemory
+
+agent = AgentMemory("your-agent-id")
+current = agent.get_working_memory()
+agent.update_working_memory("# Updated Context\n- Working on: X\n- Key fact: Y")
+```
+
+### 6. Ingest New Content
+
+Add new files to a database:
+
+```bash
+ktkn ingest --dir /path/to/files --db /path/to/output.ktkn \
+  --model bge-base-en-v1.5 --tags "source-name"
+```
+
+**Supported formats:** `.txt`, `.md`, `.json`, `.html`, `.pdf` (with extensions)
+
+### 7. Database Management
+
+```bash
+ktkn info --db archive.ktkn              # Stats: chunks, files, size, model
+ktkn list --db archive.ktkn              # List all source files in the database
+ktkn inspect --db archive.ktkn --file "document.txt"  # View chunks for a file
+ktkn delete --db archive.ktkn --file "document.txt"   # Remove a file's chunks
+ktkn vacuum --db archive.ktkn            # Reclaim space
+```
+
+## Important Rules
+
+1. **Never modify `.ktkn` files directly with SQL.** Always use the `ktkn` CLI or the Python API. The vector index and FTS index must stay in sync.
+
+2. **Embedding model must match.** A database created with `bge-base-en-v1.5` (768-dim) cannot be searched with `coreml-minilm` (384-dim). Check with `ktkn info --db ...` to see which model was used.
+
+3. **Libraries are read-only by convention.** Don't ingest into a library database. Create a new `.ktkn` for new content.
+
+4. **Working memory is ephemeral.** The `working_memory.md` file is for your current context window. Long-term facts should be stored in `memory.ktkn` via `store_memory()`.
+
+5. **Respect namespace boundaries.** Only read/write your own agent namespace. Don't modify another agent's `memory.ktkn` or `working_memory.md`.
+
+## Common Patterns
+
+### "What did the user say about X?"
+```bash
+ktkn search --db ~/.ktkn/agents/_system/conversations.ktkn --query "X" --top-k 10
+```
+
+### "Find relevant information across all libraries"
+```bash
+ktkn lib list   # see what's available
+ktkn rag --db-dir /path/to/ktkn.ktkns/ --query "X" --sources --report
+```
+
+### "Remember this for later"
+```python
+from ktkn_mem.agent import AgentMemory
+agent = AgentMemory("your-id")
+agent.store_memory("Important fact: ...", tags="key-insight")
+```
+
+### "What do I know about the user?"
+```bash
+ktkn profile show
+```
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| `ktkn: command not found` | `pip install ktkn-mem` or activate the venv |
+| `Database not found` | Check path. Use `ktkn lib list` to find mounted libraries. |
+| `No results` | Try broader query terms. Check `ktkn info --db ...` to confirm DB has content. |
+| `Embedding dimension mismatch` | The query model doesn't match the DB model. Check `ktkn info`. |
+| `CoreML model not found` | Run `ktkn init` or set `KTKN_MODEL_PATH` env var. |

ktkn_mem-1.0.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+
+# Virtual environments
+venv/
+.venv/
+
+# Database files
+*.ktkn
+
+# Swift build
+.build/
+.swiftpm/
+DerivedData/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*~
+.DS_Store
+
+# Feed data (personal)
+ktkn_feed/feeds.txt