niklas‑stephan.de

Outline KB migration 2026-10: git memories moved into collection KB (cutover done)

Last updated 05/11/2026 · outline, memory, migration, kb

Status 2026-10-31: CUTOVER DONE. Outline KB is the only writable memory store. Git memories/ and user/ are frozen history (mem new / mem save refuse to touch them; MEM_ALLOW_MEMORIES=1 overrides for maintenance). Final check before the freeze: migrate.py dry run = 79 documents unchanged. Operating details are in memory-system.

What was copied

  • 77 memories/*.md + user/user.md -> 78 documents in the Outline collection **KB** (https://docs.niklas-stephan.de). Script: /data/maintenance/outline-kb-migration/migrate.py (dry run by default, --apply to write, idempotent, never deletes; reads OUTLINE_KEY from /data/ai-persistence/.env). Rerun it after mem save to refresh the copy.
  • Format: Outline strips frontmatter, so each doc starts with a bullet header kb-id, importance, tags, updated, summary, origin, a rule, then the original body. The script matches existing docs by the kb-id line.
  • The semantic index points at KB (not AI) since 2026-10-31; verified 8 natural-language questions find the right memory (6 of 8 at rank 1, the others in the top 3 or answered by agents.md which stays in git).

Stays in git (loaded as files, not searched)

agents.md + hosts/* (rendered into /data/AGENTS.md on every host), skills/ (Zed/agent skills loaded from disk), config/ (Zed and VS Code templates), bin/mem. These are instructions, not knowledge.

Gotchas found

  • Outline titles max 100 characters (HTTP 400 validation_error); the script shortens at a word boundary, the full title is only in git.
  • Outline rewrites markup on save (- bullets to *, unwraps soft line breaks, widens table separator rows, drops \ hard breaks, re-wraps bold/code spans), so exact text comparison never matches; the script compares letters and digits only and tolerates a 3-character difference.
  • documents.list does return the full text; rate limits were not hit with 0.2 s pacing. Large docs (48 KB) work.
  • An Outline API key cannot manage API keys (403).
  • The old AI collection (30 docs) is stale: 26 of them are the origins of memories (urlId in the memory header). They are left untouched, not indexed.

Cutover (done 2026-10-31)

  1. agents.md Memory section and skill agent-memory rewritten (commit 5e36b82); rendered on handtrixxx.com, metis, iris, hestia.
  2. mem frozen for memories/ and user/; the history stays in git. kb export (manual) can write a frontmatter-markdown snapshot of KB when wanted.
  3. Secret scan: kb scan by hand (regex: ol_api_, gh[pousr]_, sk-, private key header, password|token|secret|api_key = value). No scheduled job (Niklas did not want one, 2026-10-31).
  4. importance: kept as header text; the sidecar parses it and serves list_memories(min_importance, tag) (29 high/critical of 79).
  5. Backup: Outline’s ./db and ./data are under /data, covered by Backrest plan handtrixxx-data (23:00). A restore test has not been done.
  6. Open: ThinkPad (100.64.0.8) still lacks OUTLINE_KEY and SEMANTIC_MCP_TOKEN and the kb CLI (offline when checked); do it at the next sync. Zed and VS Code clients were configured from templates but not exercised in the real apps. A restore test of outline.sql.gz into a scratch Postgres has not been done.

Source: Wiki.js