Operations

Operations

Operational notes for running and maintaining Karta.

Local Run Checklist

1. Configure env.
2. Ensure storage paths exist.
3. Start server or use Rust API.
4. Add a note.
5. Search/ask.
6. Run dreaming if needed.
7. Check schema health.

Environment

Common config areas:

• LLM provider
• embedding model
• reranker config
• Lance path
• SQLite path
• server host/port
• OAuth credentials
• ACTIVATE/read config
• dream config
• forget config

Keep secrets in env/secret manager, not checked-in docs.

Storage

Karta uses two embedded stores. SQLite is opened with journal_mode=DELETE for network-filesystem compatibility; do not assume WAL.

flowchart LR
  Karta --> Lance[(LanceDB)]
  Karta --> SQLite[(SQLite DELETE journal)]
  Lance --> Notes[Notes + embeddings]
  SQLite --> Graph[Links/dreams/rules/contradictions/schema]

Loading

Backup both stores together for consistency.

Migrations

SQLite graph store tracks schema metadata.

Expected ops:

• startup initializes tables
• pending migrations apply idempotently
• health checks expose warnings/applied/pending state

If migration fails:

1. stop writers
2. backup SQLite file
3. inspect schema metadata
4. rerun with debug logs
5. restore from backup if needed

Debug Retrieval

If answer quality poor:

1. Check notes exist.
2. Run search manually.
3. Check query mode.
4. Enable ACTIVATE if disabled.
5. Check embedding provider/config.
6. Check reranker config.
7. Run dream pass for consolidation.
8. Inspect linked notes.
9. Check contradiction injection.

Debug Write Path

If notes are not linking:

1. Check embedding generation.
2. Check similarity threshold.
3. Check candidate count.
4. Check LLM link decision output.
5. Inspect graph links.
6. Confirm add_link/add_link_typed succeeds.

Debug Dreaming

If dreams not written:

1. Confirm enabled dream types.
2. Ensure enough notes/clusters.
3. Check dream cursor.
4. Check duplicate detection.
5. Check LLM errors/token limits.
6. Inspect dream run record.

Debug Forgetting

If memories disappear:

1. Run preview first.
2. Check access stats and last_accessed_at.
3. Check protected note reasons.
4. Check archive threshold.
5. Confirm status: Active/Deprecated/Superseded/Archived.

Safe Deployment

• Keep SQLite on persistent disk.
• Keep Lance data on persistent disk.
• Use filesystem with reliable SQLite file locking; current code uses DELETE journal mode for FUSE/network-FS compatibility.
• Back up before migrations.
• Keep LLM API keys outside repo/wiki.
• Use OAuth in public deployments.
• Clamp top_k for MCP/server endpoints.

Common Failure Modes

Symptom	Likely cause	Fix
No search results	empty vector store / embedding failure	add notes, check provider.
Weak recall	ACTIVATE off / thresholds too strict	enable ACTIVATE, tune top_k/thresholds.
Bad chronological answers	missing session_id/follows links	use add_note_with_session.
No dreams	not enough notes / dream cursor already current	add notes or reset/inspect cursor.
Contradictions ignored	no contradiction dream/rule path run	run dreaming, inspect contradiction list.
Slow first query	prototype embeddings/reranker init	cache/warm startup.