CLI Reference

Complete reference for all uteke commands. Version 0.13.0.

Global Flags

Flag	Description	Default
`--store <path>`	Override store location	`~/.codecora/uteke`
`--namespace <name>`	Namespace (deprecated: prefer rooms, tags and author; writes to a non-default namespace print a warning on stderr, see Namespaces are deprecated)	`default`
`--json`	Output as JSON	off
`--verbose`	Enable debug logging	off

Config file path is auto-resolved (~/.codecora/uteke/uteke.toml + .uteke/uteke.toml); there is no --config flag.

uteke onboard

Interactive onboarding wizard — guides new users from zero to productive. Detects install, picks agent, configures extraction mode, toggles features, writes config, installs agent integration, runs a memory test, and introduces Rooms.

bash

# Interactive (recommended for first-time users)
uteke onboard

# Non-interactive (defaults: agent=hermes, namespace=default, tool mode, offline extraction)
uteke onboard --yes

# Pre-select agent and namespace
uteke onboard --yes --agent claude --namespace work

Flag	Description
`--yes`	Skip interactive prompts, use defaults
`--agent <name>`	Pre-select agent (hermes, claude, cursor, pi, opencode)
`--namespace <name>`	Pre-select namespace

The wizard steps:

Install detection — checks if uteke is on PATH and if a store exists
Agent selection — Hermes, Claude, Cursor, Pi, or OpenCode
Integration mode — manual tool vs memory-provider (auto recall + extraction)
Namespace — for multi-agent isolation
Feature toggles — toggle ON/OFF for: Aging, Auto-maintenance, Graph rerank, Salience boost, Recency boost, Server mode
Config write — generates ~/.codecora/uteke/uteke.toml
Agent init — runs uteke init with your selections
Feature showcase — prints all commands grouped by category

uteke upgrade

Check for updates and upgrade to the latest Uteke release.

bash

uteke upgrade
uteke upgrade --yes

Flag	Description
`--yes`	Skip confirmation prompt

Note: Renamed from uteke update in v0.7.0 to avoid conflict with uteke doc update. Verifies the minisign signature of checksums-sha256.txt and then the archive's SHA-256 by default; a missing or invalid signature aborts the upgrade, as does a release older than the installed version or a non-stable (pre-release) one; uteke upgrade installs only stable releases (see SECURITY.md). Only uteke upgrade checks the signature; install.sh, install.ps1 and Homebrew do not. Set UTEKE_UPGRADE_SKIP_CHECKSUM=1 to skip both checks (not recommended).

uteke remember

Store a new memory with optional tags, metadata, and contradiction detection.

bash

# Basic
uteke remember "Deploy v2.1 to staging Friday" --tags deploy,staging

# With metadata enrichment
uteke remember "Deploy staging to AWS us-east-1" \
  --tags deploy,aws \
  --entity staging-server \
  --category infrastructure \
  --meta "source:meeting-note,confidence:0.9"

# With contradiction detection
uteke remember "Server runs on port 8080" --tags config --detect-contradiction

# With memory type
uteke remember "API rate limit is 1000/min" --type fact

# With source attribution (#348)
uteke remember "Deploy at 3pm Friday" --tags deploy --source "https://slack.com/msg/123" --source-type url

# In a specific namespace
uteke remember "User prefers dark mode" --tags pref --namespace my-agent

Flag	Description
`--tags <tags>`	Comma-separated tags
`--entity <name>`	Associate memory with an entity (e.g. "staging-server")
`--category <cat>`	Categorize the memory (e.g. "infrastructure")
`--meta <pairs>`	Key:value pairs, comma-separated. Auto-detects type (string/number/bool)
`--type <type>`	Memory type: fact, procedure, preference, decision, context, note, insight, reference, event
`--source <url-or-path>`	Source attribution (URL, file path, or description)
`--source-type <type>`	Source type: user, url, file, import, derived, system (default: user)
`--detect-contradiction`	Detect conflicting memories (default threshold: 0.65)
`--room <room_id>`	Link memory to a room (collaborative context)
`--author <name>`	Author attribution when storing in a room
`--json`	Output stored memory as JSON

uteke recall

Unified search combining vector similarity with FTS5 full-text search, ranked by Reciprocal Rank Fusion (RRF). Default strategy since v0.16.0: fusion — a weighted RRF of the vector and hybrid rankings. Searches both memories and documents by default (unified mode). Hot memories (accessed within 7 days) get a score boost.

bash

uteke recall "What framework does the API use?"
uteke recall "deployment" --limit 10
uteke recall "database config" --namespace hermes --json
uteke recall "server" --entity staging-server --json
uteke recall "config" --category infrastructure --limit 5
# Search documents only
uteke recall "API architecture" --type doc
# Search memories only (backward compatible)
uteke recall "deployment" --type memory
# Explain mode (#1160): show the ranking signals behind each result
uteke recall "database caching" --explain
# Budgeted context pack (#1281): bounded selection for prompt injection
uteke recall "database caching" --pack --budget 4000
uteke recall "database caching" --pack --exclude-ids abc123,def456

Flag	Description
`--type <type>`	Search scope: `all` (default — memories + documents, unified via RRF), `memory` (memories only), `doc` (documents only)
`--limit <n>`	Max results (default: 5)
`--entity <name>`	Filter results to a specific entity
`--category <cat>`	Filter results to a specific category
`--content-format <fmt>`	Content display: `auto` (detect), `text`, `json` (pretty-print JSON memories)
`--where <key=value>`	Filter by JSON field on structured memories (e.g. `--where role=CTO`)
`--explain`	Show the ranking signals behind each result (#1160): final score, strategy, vector similarity + rank, FTS rank, RRF score with per-channel fusion contributions, and jaccard/salience/recency/graph boost deltas. Memory-only — not available with `--type doc`
`--pack`	Return a budgeted context pack (#1281) instead of a bare ranked list: `{selected, skipped, budget_used, budget_chars}`. Rank-order preserving greedy fill of the character budget; deterministic and LLM-free
`--budget <chars>`	Character budget for `--pack` (default: 4000)
`--exclude-ids <ids>`	Memory IDs already injected this turn, comma-separated — excluded from the pack and reported as `skipped[reason=excluded]`
`--json`	Output as JSON array

uteke search

Keyword text search with tag filtering.

bash

uteke search "monorepo"
uteke search "deploy" --tags staging,prod --limit 20
uteke search "api" --namespace backend --json

Flag	Description
`--tags <tags>`	Filter by comma-separated tags
`--limit <n>`	Max results (default: 10)
`--json`	Output as JSON

uteke list

List memories with optional tag, entity, category filter and pagination.

bash

uteke list --limit 20
uteke list --tag deploy --offset 10 --json
uteke list --entity staging-server --json
uteke list --category infrastructure --limit 10
uteke list --namespace hermes
uteke list --at 2026-06-01T12:00:00Z   # Time-travel: list at point in time

Flag	Description
`--tag <tag>`	Filter by single tag
`--entity <name>`	Filter by entity name
`--category <cat>`	Filter by category
`--limit <n>`	Max results (default: 20)
`--offset <n>`	Skip first N results
`--at <timestamp>`	Query memories at point in time (RFC3339)
`--json`	Output as JSON

uteke forget

Delete memories by ID, tag, tier, or all. Supports bulk operations.

bash

# Delete single memory
uteke forget <uuid> --confirm

# Delete all with a tag
uteke forget --tag deploy --confirm

# Delete all cold-tier memories (>30 days old)
uteke forget --cold --confirm

# Delete everything in namespace
uteke forget --all --confirm

# Preview without deleting
uteke forget --tag stale --dry-run

Flag	Description
`--tag <tag>`	Delete all memories with this tag
`--cold`	Delete all cold-tier memories (>30 days)
`--all`	Delete all memories in namespace
`--confirm`	Skip confirmation prompt
`--dry-run`	Preview what would be deleted

uteke consolidate

Find and merge duplicate memories using cosine similarity.

bash

# Preview duplicates (dry run)
uteke consolidate --threshold 0.60 --dry-run

# Merge duplicates
uteke consolidate --threshold 0.60

# Higher threshold = more conservative (default: 0.90)
uteke consolidate --dry-run

Recommended threshold: 0.60–0.70 for small embedding models (embeddinggemma-q4). Keeps newer memory, removes older.

uteke prune

Remove deprecated and expired temporal memories.

bash

# Preview what would be pruned
uteke prune --ttl 30 --dry-run

# Prune deprecated/expired memories
uteke prune --ttl 30

uteke lifecycle

Safe memory lifecycle management: deprecate, promote, and inspect lifecycle status.

bash

# Show lifecycle status (active vs deprecated counts + config)
uteke lifecycle status

# Scoped to a namespace
uteke lifecycle status --namespace my-agent

# Run a lifecycle cycle (deprecate aged + prune expired)
uteke lifecycle cycle

# Scoped cycle
uteke lifecycle cycle --namespace my-agent

# Promote a deprecated memory back to active
uteke lifecycle promote <memory-id>

# Restore is an alias for promote
uteke lifecycle restore <memory-id>

Subcommand	Description
`status`	Show active/deprecated counts and lifecycle config
`cycle`	Run lifecycle cycle (deprecate aged memories + prune expired)
`promote <id>`	Restore a deprecated memory to active status
`restore <id>`	Alias for `promote`

See Configuration → Memory Lifecycle for lifecycle config options.

uteke provenance

Show the full provenance report for a memory (#1172) — who wrote it, from what source, its trust tier, whether the content still matches the hash recorded at write time, and the complete event chain with actor + evidence.

bash

# Human-readable audit report
uteke provenance <memory-id>

# JSON (for tooling)
uteke provenance <memory-id> --json

Hash verdicts: ✓ matches (content unchanged since write), ✗ MISMATCH (content modified after write — investigate), — (memory predates schema v18; hash will be recorded on next content update).

uteke supersede

Resolve a conflict: mark the old memory superseded by a newer one (#1053) — wires the supersession edge pair, soft-deprecates the old memory, and records the resolution in the contradiction ledger (#1172).

bash

uteke supersede <old-memory-id> <new-memory-id> --reason "decision pivot"

uteke contradictions

Inspect the contradiction resolution ledger (#1172) — memories that were superseded by conflict resolution and are not restored.

bash

# List the resolution ledger
uteke contradictions list

# Filter by namespace, cap entries
uteke contradictions list --namespace ops --limit 20

# JSON (for tooling)
uteke contradictions list --json

# Restore a superseded memory (full UUID or unambiguous prefix)
uteke contradictions undo <memory-id>

uteke namespace

Manage namespaces — list, inspect, switch defaults, and manage members (#1181).

bash

# List all namespaces with counts
uteke namespace list

# Show stats for a namespace
uteke namespace stats my-agent

# Switch default namespace (saved to config)
uteke namespace switch my-agent

# Move a memory to another namespace (#1181 — no re-embed)
uteke namespace move <memory-id> other-ns

# Rename a namespace — merges into an existing target (#1181)
uteke namespace rename old-ns new-ns

# Delete a namespace with an explicit strategy for its memories (#1181)
uteke namespace delete temp-ns --strategy merge --target archive --confirm
uteke namespace delete ghost-ns --strategy deprecate --confirm

Delete strategies: refuse (default — refuses while any memory references the name), merge (move all memories to --target, the name vanishes), or deprecate (soft-delete — restorable via uteke lifecycle/promote, never hard-deleted). --confirm is required for delete.

Namespace resolution order: --namespace flag → UTEKE_NAMESPACE env → uteke.toml → "default"

uteke tags

Manage tags across all memories.

bash

# List all tags with counts
uteke tags list --by-count

# Rename a tag
uteke tags rename old-tag new-tag

# Delete a tag from all memories
uteke tags delete unused-tag

uteke recall — Advanced Flags

Additional flags not shown in the basic example above:

bash

# Minimum similarity score filter
uteke recall "database config" --min 0.7
uteke recall "database config" --strict    # uses min_score_strict (default 0.5)
uteke recall "database config" --min 0.25  # opt-in similarity threshold (default 0.0 since #1223: fusion scores are rank-based)

# Time-travel: query memories at specific point in time
uteke recall "deployment process" --at 2026-06-01T12:00:00Z

# Relationship graph traversal
uteke recall "auth" --related --depth 2

# Recall strategy (fusion | vector | fts5 | hybrid | graph)
uteke recall "auth" --strategy fusion   # default since 0.16.0 — weighted RRF of vector + hybrid rankings
uteke recall "auth" --strategy hybrid   # vector + FTS5 fused via RRF (k=60)
uteke recall "auth" --strategy vector   # vector similarity only
uteke recall "auth" --strategy fts5     # full-text search only
uteke recall "auth" --strategy graph    # hybrid + graph-signal reranking (#378)

`--strategy graph` (Graph-augmented RAG)

The graph strategy runs the hybrid (RRF) pipeline, then fuses graph signals from the memory_edges table into each result's score. A memory that is well-connected in the graph (referenced by many others, high edge density) drifts upward; isolated memories are untouched.

The boost is additive and log-scaled, so it saturates quickly and never lets a single hub dominate. Configure the weights under [recall] in uteke.toml (see Configuration):

bash

# Subtle boost (default): well-connected memories nudge up slightly
uteke recall "architecture" --strategy graph

# Stronger authority boost via env var
UTEKE_GRAPH_AUTHORITY_WEIGHT=0.3 uteke recall "architecture" --strategy graph

Cold start (no edges yet): graph behaves identically to hybrid — the boost is zero when there are no signals.

AI-context output

bash

uteke recall "api design" --context

Flag	Description
`--min <score>`	Minimum similarity score (0.0-1.0)
`--strict`	Use strict threshold (`min_score_strict`, default 0.5)
`--min <score>`	Minimum similarity score threshold (default 0.0 since 0.17.x, #1223 — fusion scores are rank-based, not cosine)
`--at <timestamp>`	Query memories at point in time (RFC3339)
`--related`	Follow relationship edges
`--depth <n>`	Traversal depth for --related
`--context`	AI-prompt formatted output
`--salience`	Salience boost is on by default with weight 0.1; passing `--salience` uses the configured `[recall] salience_weight` (default 0.15) instead. `--no-salience` disables it
`--recency`	Recency boost is on by default with weight 0.1; passing `--recency` uses the configured `[recall] recency_weight` (default 0.15) instead. `--no-recency` disables it
`--jaccard`	Enable Jaccard token reranking signal (default: off, requires `jaccard_weight` > 0 in config)

Reading recall scores (#1405)

A recall score is base_score + boosts, and the base means something different per strategy. Scores are for ordering results within one query; they are not a similarity percentage and are not comparable across strategies, queries or stores.

Strategy	`base_score`	Typical range of the base
`fusion` (default)	Weighted RRF of the vector and hybrid rankings: `1.7 / (60 + rank_v + 1) + 1.0 / (60 + rank_h + 1)`. A function of rank, not of similarity	at most about `0.044` (rank 1 in both)
`hybrid`	RRF of the vector and FTS5 rankings divided by the best possible sum, so a memory at the top of both rankings is about `1.0`	up to `1.0`
`vector`	The vector similarity of the query and the memory	up to about `1.0`
`fts5`	Normalised keyword rank (rank 1 is `1.0`)	up to `1.0`

Boosts are added on top and are not capped, so a final score can exceed 1.0 (for example 1.1169 for a hybrid result):

salience_boost = salience score x salience weight. The salience score combines importance, access signal and pinned state.
recency_boost = recency score x recency weight. A memory created just now has recency score 1.0; it decays with the memory type's half-life.
jaccard_boost and graph_boost apply only when those signals are enabled.

Both weights are 0.1 by default, in the CLI and in uteke-serve alike. The configured [recall] weights (default 0.15) are used only when --salience / --recency are passed explicitly, and uteke-serve does not read them yet (#1355).

The salience score includes an access signal, so scores drift up a little as a memory is recalled: in a three-recall test on a fresh store salience_boost went 0.025, 0.02676, 0.02977. Do not expect the same query to return exactly the same scores twice.

Because fusion's base is so small, the boosts dominate its absolute value, and two memories at neighbouring ranks have final scores that differ only in the third or fourth decimal. Rounded to three decimals they can look identical even though the order is decided. Use --explain for the exact breakdown; this is the output for the top result of a default (fusion) recall:

json

{
  "strategy": "fusion",
  "final_score": 0.16899788,
  "base_score": 0.043997884,
  "vector_similarity": 0.76310307,
  "vector_rank": 1,
  "rrf_score": 0.043997884,
  "fusion_vector_contribution": 0.027868852,
  "fusion_hybrid_contribution": 0.016129032,
  "salience_boost": 0.025,
  "recency_boost": 0.1
}

Here 0.16899788 = 0.043997884 (rrf_score) + 0.025 (salience) + 0.1 (recency).

What this means for thresholds: --min compares against the final score, so a value that makes sense for vector (similarity scale) removes everything in fusion (base around 0.04), and a small value keeps almost everything in hybrid or fts5. The default is 0.0 for this reason (#1223); only set --min after looking at --explain output for your own queries and strategy.

uteke room

Room-based memory management:

bash

# Create a room
uteke room create "project-kickoff" --title "Project Kickoff"

# List rooms (cross-namespace by default, #392)
uteke room list
uteke room list --namespace my-agent  # scoped

# Show room stats and participants
uteke room stats "project-kickoff"

# Recall within a room (semantic)
uteke room recall "project-kickoff" --query "database decision"

# Generate structured document from room
uteke room document "project-kickoff"

# Room summary (LLM-free, tag clustering)
uteke room summary "project-kickoff"

# Delete room (memories are NOT deleted, only room links)
uteke room delete "project-kickoff" --confirm

# Link a document to a room (#859, positional slug)
uteke room add-document "project-kickoff" "architecture-spec"

# Unlink a document from a room (#859)
uteke room remove-document "project-kickoff" "architecture-spec"

# List documents linked to a room (#859)
uteke room list-documents "project-kickoff"

# List rooms that reference a document (#859, positional slug)
uteke room list-rooms "architecture-spec"

# Consolidate a room's memories (#1088) — dry-run by default, no LLM calls
uteke room consolidate "project-kickoff"

# Execute consolidation (LLM calls + writes; budget-capped)
uteke room consolidate "project-kickoff" --apply --max-calls 20

Room consolidation notes (#1088)

Dry-run default: shows memory count, batches, and estimated LLM calls — zero API calls.
--apply requires LLM config (same [extraction] setup as import --extract).
--max-calls (default 10) is a hard budget: failed LLM calls count too, batches beyond the cap are skipped.
Source memories are soft-deprecated (never deleted), each carrying a consolidated into <id> reason.
New consolidated records pass a provenance policy gate (hedging language, trust tier) before being written.

uteke bench

Run performance benchmarks with synthetic data:

bash

# Default: 100, 1000, 10000 memories
uteke bench

# Custom counts
uteke bench --counts 500,5000

# JSON output
uteke bench --json

Measures insert throughput, recall latency (avg + p95), and storage footprint.

uteke pin / unpin

Pin memories so they never decay:

bash

uteke pin <id>
uteke unpin <id>

uteke importance

Recalculate importance scores:

bash

uteke importance

uteke aging

Memory aging management with auto-cleanup.

bash

# Show hot/warm/cold breakdown
uteke aging status

# Preview memories older than 90 days
uteke aging preview --older-than-days 90

# Delete memories older than 180 days
uteke aging cleanup --older-than-days 180 --yes

Subcommand	Flags	Description
`status`	—	Show hot/warm/cold/never-accessed counts
`preview`	`--older-than-days N` (default 180), `--max-access-count N` (default 1)	Dry-run preview of cleanup candidates
`cleanup`	`--older-than-days N` (default 180), `--max-access-count N` (default 1), `--yes`	Delete aged memories (`--yes` skips confirmation)

uteke import

Import memories from a file (or stdin with -). Format is auto-detected from the extension and content; override with --format.

bash

# Import JSONL exported by `uteke export`
uteke import memories.jsonl

# Import markdown/plain text (split into chunks)
uteke import notes.md --tags imported,notes

LLM fact extraction (`--extract`)

Raw source material (chat transcripts, long notes, exported dumps) is noisy: greetings, filler, boilerplate. Importing it verbatim pollutes recall. With --extract, uteke first sends the text to an OpenAI-compatible chat-completions endpoint, asks the model to distill it into atomic facts, and stores one memory per fact.

This is opt-in. Without --extract, import makes no network calls and stays fully offline.

bash

# Distill a transcript into atomic facts before storing
uteke import session.txt --extract \
  --extract-model gpt-4o-mini \
  --extract-base-url https://api.openai.com/v1 \
  --extract-api-key sk-...

# Use a local Ollama model
uteke import notes.md --extract \
  --extract-model llama3.1 \
  --extract-base-url http://localhost:11434/v1

Settings resolve in this order: CLI flag > UTEKE_EXTRACTION_* env var > [extraction] config section > built-in default. The API key falls back to the embedding / OPENAI_API_KEY credential, so an existing OpenAI-compatible setup needs no duplicate key.

Flag	Description
`--extract`	Enable LLM extraction (off by default)
`--extract-model <M>`	Override the chat model
`--extract-base-url <U>`	Override the endpoint base URL
`--extract-api-key <K>`	Override the API key
`--extract-max-facts <N>`	Cap facts kept per document (0 = default)

See configuration for the [extraction] config block and UTEKE_EXTRACTION_* environment variables.

Scene-segmented output (#1009)

When the LLM extracts facts, it groups them by topic (scene) and assigns a priority score (0.0–1.0) to each. This means:

Scene tags — each fact gets a scene:<topic> tag automatically, so you can filter by topic during recall.
Priority — important decisions get higher importance (0.7–0.9), routine facts get lower (0.3–0.5).
Type — facts are tagged with a semantic type (decision, fact, preference, etc.) when the model provides one.

Offline extraction (no LLM) is unaffected — it continues to produce flat strings with default importance.

Batch import (`--batch-dir`)

Import all files from a directory in one command. Each file is processed according to its type:

Extension	Strategy	Description
`.md` / `.markdown`	Document (default)	Full content → auto-chunk → embed. No LLM.
`.md` + `--extract`	Memory extract	LLM fact extraction → atomic facts → embed.
`.txt` / `.jsonl`	Memory extract	LLM fact extraction (requires `--extract`).
`.txt` / `.jsonl` + `--as-doc`	Document override	Import as document, skip LLM.

bash

# Dry run — preview what would be imported
uteke import --batch-dir ./knowledge --dry-run

# Import all markdown as documents (no LLM, fully offline)
uteke import --batch-dir ./docs --recursive --tags docs

# Import with LLM fact extraction
uteke import --batch-dir ./notes --extract \
  --extract-model gpt-4o-mini \
  --extract-base-url https://api.openai.com/v1 \
  --tags imported

# Force all files as documents (skip extraction)
uteke import --batch-dir ./raw --as-doc --recursive

# Limit file size (default: 1MB)
uteke import --batch-dir ./large-docs --max-size 500000

Flag	Description
`--batch-dir <PATH>`	Directory to import (enables batch mode)
`--recursive`	Recurse into subdirectories
`--as-doc`	Force all files as documents (skip LLM extraction)
`--as-memory`	Force all files through LLM extraction
`--max-size <BYTES>`	Skip files larger than N bytes (default: 1,000,000)
`--dry-run`	Preview files and strategies without importing

uteke graph

Knowledge graph operations (v0.2.0). Nodes and edges stored in SQLite (graph_nodes, graph_edges tables, schema v7).

bash

# List all nodes (optionally filter by entity type)
uteke graph nodes
uteke graph nodes --entity-type person

# List all edges (optionally filter by relation)
uteke graph edges --relation owns

# Find neighbors of a node via BFS
uteke graph neighbors alice --depth 2

# Shortest path between two nodes
uteke graph path alice "project-x" --max-depth 5

# Query edges by relation type
uteke graph query part_of

# Show graph statistics
uteke graph stats

Subcommand	Flags	Description
`nodes`	`--entity-type <t>`	List graph nodes
`edges`	`--relation <r>`	List graph edges
`neighbors <label>`	`--depth N` (default 1)	BFS neighbors of a node
`path <source> <target>`	`--max-depth N` (default 5)	BFS shortest path
`query <relation>`	—	Query edges by relation type
`stats`	—	Show graph statistics

uteke edges

List auto-wired edges for a memory (v0.2.1, #346). Edges are auto-extracted from content on every remember() call using pure pattern matching — no LLM.

Supported patterns

Pattern	Edge type	Resolved via
`[[slug]]`	`references`	`memories.slug` lookup
`@tag`	`tagged_as`	most recent memory with that tag
`^<uuid>`	`supersedes`	direct memory UUID
`><uuid>`	`replies_to`	direct memory UUID
`rel:<type>:<uuid>` in `--meta`	`<type>`	direct memory UUID (legacy compat)

Usage

bash

# List direct edges (both directions)
uteke edges <memory-id>

# Multi-hop BFS across the edge table
uteke edges <memory-id> --deep 2

# Only show incoming edges (backlinks)
uteke edges <memory-id> --direction incoming

# JSON output
uteke edges <memory-id> --json

With --deep N, returns memory ids reachable within N hops (cycles detected, start excluded).

--direction accepts incoming, outgoing, or both (default both).

uteke rebuild-backlinks

Rebuild referenced_by backlinks from existing forward edges (v0.2.1, #350).

Every forward edge (references, tagged_as, supersedes, replies_to) automatically gets an inverse referenced_by edge on remember(). This command repairs stores that pre-date #350, or were written to via the low-level edge API. Idempotent.

bash

# Rebuild and print a summary
uteke rebuild-backlinks

# Print only the count of new backlinks (script-friendly)
uteke rebuild-backlinks --quiet

# JSON output
uteke rebuild-backlinks --json

uteke dream

Run the full maintenance pipeline in one command (v0.2.1, #353).

Executes phases in dependency order: lint → backlinks → dedup → contradict → orphans → compact → verify. Each phase records its status. Errors in individual phases are recorded but do not abort the pipeline.

bash

# Run all phases
uteke dream

# Run specific phases only
uteke dream --phases lint,orphans

# Dry-run (preview what would change)
uteke dream --dry-run

# Scoped to a namespace
uteke dream --namespace my-agent

# Run only contradiction detection
uteke dream --phases contradict

Flag	Description
`--phases <list>`	Comma-separated subset: lint, backlinks, dedup, contradict, orphans, compact, verify
`--dry-run`	Preview without making changes
`--namespace <ns>`	Run scoped to a specific namespace (backlinks and verify are global)
`--json`	JSON output

Phases

Phase	Description
`lint`	Check for invalid memory types, missing slugs, stale deprecated flags
`backlinks`	Rebuild `referenced_by` edges (same as `rebuild-backlinks`)
`dedup`	Find and merge near-duplicate memories (cosine ≥ 0.90)
`contradict`	Detect contradictory memories (threshold 0.65) and flag for review
`orphans`	Find disconnected, low-importance memories
`compact`	Apply auto-prune to cold-tier and deprecated memories
`verify`	Verify DB and index consistency

uteke feedback

Record feedback on a memory's usefulness (v0.8.0, #718). Adjusts importance score: +0.05 for helpful, -0.10 for unhelpful.

bash

uteke feedback helpful <memory-id>
uteke feedback unhelpful <memory-id>

With --json flag, outputs structured JSON with id, feedback type, delta, and new importance value.

uteke orphans

Find orphan memories — disconnected nodes with low importance and few accesses (v0.2.1, #351).

bash

# Find orphans with default thresholds
uteke orphans

# Custom thresholds
uteke orphans --min-age-days 14 --max-access-count 3

# JSON output for scripting
uteke orphans --json

Flag	Description
`--min-age-days <n>`	Minimum age in days (default: 7)
`--max-access-count <n>`	Maximum access count (default: 2)
`--limit <n>`	Max results (default: 50)
`--namespace <ns>`	Scope to namespace
`--json`	JSON output

uteke timeline

View chronological event log for a memory (v0.2.1, #347).

Every memory has an audit trail: creation, updates, type changes, supersession, edge additions, and pin/unpin events.

bash

# Show timeline for a memory
uteke timeline <memory-id>

# Limit to last N events
uteke timeline <memory-id> --limit 10

# JSON output
uteke timeline <memory-id> --json

Flag	Description
`--limit <n>`	Max events (default: 50)
`--json`	JSON output

Other Commands

Command	Description
`uteke get <id>`	Retrieve a single memory by UUID
`uteke forget <id>`	Delete a memory by UUID
`uteke forget --tag <tag>`	Delete all memories with a tag
`uteke forget --cold`	Delete all cold-tier memories
`uteke forget --all`	Delete all memories in namespace
`uteke consolidate`	Find and merge duplicate memories
`uteke prune`	Remove deprecated/expired memories
`uteke stats`	Show store statistics with tier breakdown
`uteke export`	Export memories to JSONL (no embeddings) · `--full` = structural export: manifest + rooms/graph/edges/documents/chunks/timeline (round-trips the whole store, format `structural-v1`)
`uteke import <file>`	Import memories from JSONL/Markdown/text (`--extract` distills with an LLM) — auto-detects structural exports (manifest first line) and restores the full store; restored memories re-embed via `uteke repair --reembed`
`uteke doctor`	Health check (DB, index, model, consistency)
`uteke verify`	Verify DB and index consistency
`uteke verify-checksums --binary <path>`	Verify binary integrity against SHA256 checksums
`uteke repair`	Rebuild index from SQLite
`uteke repair --rebuild`	Rebuild index from SQLite (explicit)
`uteke repair --reembed`	Regenerate missing embeddings for memories without vectors (#906)
`uteke namespace list`	List all namespaces with memory counts
`uteke namespace stats <name>`	Show stats for a namespace
`uteke namespace switch <name>`	Set default namespace in config
`uteke namespace move <id> <ns>`	Move a memory to another namespace, no re-embed (#1181)
`uteke namespace rename <old> <new>`	Rename a namespace; existing target = merge (#1181)
`uteke namespace delete <ns> --confirm`	Delete a namespace (`--strategy refuse\|merge\|deprecate`, #1181)
`uteke hook <shell>`	Print shell hook script (bash/zsh/fish)
`uteke init --agent <type>`	Initialize integration (opencode, pi, claude, cursor, hermes)
`uteke init --agent hermes --memory-provider`	Install uteke as Hermes's default memory provider (auto recall + extraction). See Hermes integration, Mode B. Note: Hermes Mode B deprecated — see integrations/hermes.md for migration.
`uteke init --agent pi --memory-provider`	Install uteke as pi's default memory provider (auto recall + extraction, #575/#577)
`uteke init --agent claude --memory-provider`	Install uteke as Claude Code's default memory provider (auto recall + extraction, #575/#577)
`uteke init --agent cursor --memory-provider`	Install uteke as Cursor's default memory provider (auto recall + extraction, #575/#577)
`uteke init --agent opencode`	Generate AGENTS.md with uteke instructions for OpenCode (#612)
`uteke completions <shell>`	Generate shell completions

uteke-serve (Server Mode)

Start a persistent HTTP server for fast AI agent access. Eliminates cold start (~980ms → ~21ms per operation).

bash

# Start server on default port (8767)
uteke-serve

# Custom port
uteke-serve --port 9000

# With logging
RUST_LOG=info uteke-serve --port 8767

When [server] enabled = true is set in config, the CLI auto-routes commands through the server. Falls back to local store if server is not running.

HTTP Endpoints

See the HTTP API Reference for the complete list of 50+ endpoints, request/response schemas, and examples.

MCP Server

Two MCP transport modes are available (v0.2.1, #381):

bash

# stdio transport (for Claude Desktop, Cursor, etc.)
uteke-mcp

# HTTP transport (POST /mcp on uteke-serve)
curl -X POST http://127.0.0.1:8767/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'

Protocol version: 2025-06-18 (Streamable HTTP spec).

Document Commands (#406, #411, #438, #440)

Wiki/knowledge base engine — hierarchical documents with auto-chunking, tree operations, and hybrid search.

`uteke doc create`

Create or update a document from file, content, or stdin.

bash

# From file
uteke doc create architecture --file guide.md --tags wiki,tech

# From inline content
uteke doc create notes --content "# Notes\n\nQuick notes" --title "My Notes"

# From stdin
cat README.md | uteke doc create readme --file -

# As child of another document
uteke doc create chapter1 --parent book --file ch1.md

Flag	Description
`--title <title>`	Document title (auto-derived from first `#` heading if omitted)
`--file <path>`	Read content from file (`-` for stdin)
`--content <text>`	Inline content (alternative to `--file`)
`--tags <tags>`	Comma-separated tags
`--parent <slug>`	Parent document slug (creates as child, #438)

`uteke doc get`

Get a document by slug or ID.

bash

uteke doc get architecture
uteke doc get architecture --json

`uteke doc list`

List all documents (global — not namespace-scoped, v0.7.0).

bash

uteke doc list --limit 20
uteke doc list --tree          # Indented tree view
uteke doc list --roots-only   # Root documents only

Flag	Description
`--limit <n>`	Max results (default: 20)
`--tree`	Show as indented tree (recursive children)
`--roots-only`	Show only root documents (no parent)

`uteke doc search`

Search documents using hybrid, semantic, or FTS5 search (#440).

bash

uteke doc search "authentication flow"
uteke doc search "database" --mode semantic
uteke doc search "API reference" --mode fts --limit 5

Flag	Description
`--mode <mode>`	`hybrid` (default), `semantic`, or `fts`
`--limit <n>`	Max results (default: 5)

`uteke doc update`

Partially update a document — only provided fields are changed (#589). Content changes trigger chunk rebuild; metadata-only or title-only updates skip it.

bash

# Update title only (no chunk rebuild)
uteke doc update architecture --title "New Architecture Guide"

# Update content from file (triggers chunk rebuild)
uteke doc update architecture --file updated-guide.md

# Update content from stdin
echo "# New content" | uteke doc update architecture --file -

# Replace tags
uteke doc update architecture --tags wiki,tech,v2

# Replace metadata
uteke doc update architecture --metadata '{"draft": false, "reviewer": "CTO"}'

# Multiple fields at once
uteke doc update architecture --title "Final Guide" --tags wiki,published

Flag	Description
`--title <title>`	New title (no chunk rebuild)
`--content <text>`	New content (triggers chunk rebuild)
`--file <path>`	Read new content from file (`-` for stdin; triggers chunk rebuild)
`--tags <tags>`	Replace tags (comma-separated)
`--metadata <json>`	Replace metadata (JSON string)

At least one field is required. Omitted fields are left unchanged.

`uteke doc move`

Move a document to a new parent or root (#438).

bash

uteke doc move chapter1 --parent new-book
uteke doc move orphan-doc               # Move to root

`uteke doc delete`

Delete a document by ID or slug (cascades to children and chunks).

bash

uteke doc delete architecture
uteke doc delete <id>

`uteke doc export`

Export all documents as JSON or markdown.

bash

uteke doc export           # markdown to stdout
uteke doc export --json    # JSON to stdout

Graph API (#408, #542)

Visualization

bash

# All nodes + edges + stats
curl http://127.0.0.1:8767/graph

# Response: { nodes: [...], edges: [...], stats: {...} }

Mutation

bash

# Create a typed edge
curl -X POST http://127.0.0.1:8767/graph/edge \
  -H "Content-Type: application/json" \
  -d '{"from": "<uuid>", "to": "<uuid>", "edge_type": "references"}'

# Delete an edge by ID
curl -X DELETE "http://127.0.0.1:8767/graph/edge?id=<edge-uuid>"

Server Authentication (#409)

Dual-role API token model:

Flag / Env	Role	Access
`--auth-token` / `UTEKE_AUTH_TOKEN`	Admin	All endpoints (GET, POST, DELETE)
`--read-only-token` / `UTEKE_READ_ONLY_TOKEN`	ReadOnly	All read endpoints (GET + POST search/list/graph). 403 on writes.

bash

# Start with dual tokens
uteke-serve --auth-token admin-secret --read-only-token viewer-key

# Read-only client (GET only)
curl -H "Authorization: Bearer viewer-key" http://127.0.0.1:8767/stats

# Write attempt fails
curl -X POST -H "Authorization: Bearer viewer-key" ...  # 403 Forbidden

Configurable Limits (#404)

All limits can be overridden via env vars or [limits] config section:

Env Var	Config Key	Default	Description
`UTEKE_MAX_CONTENT_LENGTH`	`max_content_length`	100000	Max memory content (chars, 0=disable)
`UTEKE_MAX_TAGS_COUNT`	`max_tags_count`	20	Max tags per memory
`UTEKE_MAX_TAG_LENGTH`	`max_tag_length`	50	Max single tag length (chars)
`UTEKE_MAX_PAYLOAD_SIZE`	`max_payload_size`	10485760	Max server payload (bytes)
`UTEKE_DEFAULT_RECALL_LIMIT`	`default_recall_limit`	5	Default recall limit

Changelog

v0.6.5

Room fixes (#545/#546/#547/#549/#550): Fixed room creation race conditions, room memory list pagination, room summary edge cases, room document generation for empty rooms, and room delete cascade consistency.

v0.6.6

Room summary Unicode fix (#565): Summary truncation now uses char boundaries instead of byte offsets, preventing mid-character cuts in multi-byte content.

CLI Reference ​

Global Flags ​

uteke onboard ​

uteke upgrade ​

uteke remember ​

uteke recall ​

uteke search ​

uteke list ​

uteke forget ​

uteke consolidate ​

uteke prune ​

uteke lifecycle ​

uteke provenance ​

uteke supersede ​

uteke contradictions ​

uteke namespace ​

uteke tags ​

uteke recall — Advanced Flags ​

--strategy graph (Graph-augmented RAG) ​

AI-context output ​

Reading recall scores (#1405) ​

uteke room ​

Room consolidation notes (#1088) ​

uteke bench ​

uteke pin / unpin ​

uteke importance ​

uteke aging ​

uteke import ​

LLM fact extraction (--extract) ​

Scene-segmented output (#1009) ​

Batch import (--batch-dir) ​

uteke graph ​

uteke edges ​

Supported patterns ​

Usage ​

uteke rebuild-backlinks ​

uteke dream ​

Phases ​

uteke feedback ​

uteke orphans ​

uteke timeline ​

Other Commands ​

uteke-serve (Server Mode) ​

HTTP Endpoints ​

MCP Server ​

Document Commands (#406, #411, #438, #440) ​

uteke doc create ​

uteke doc get ​

uteke doc list ​

uteke doc search ​

uteke doc update ​

uteke doc move ​

uteke doc delete ​

uteke doc export ​

Graph API (#408, #542) ​

Visualization ​

Mutation ​

Server Authentication (#409) ​

Configurable Limits (#404) ​

Changelog ​

v0.6.5 ​

v0.6.6 ​

CLI Reference

Global Flags

uteke onboard

uteke upgrade

uteke remember

uteke recall

uteke search

uteke list

uteke forget

uteke consolidate

uteke prune

uteke lifecycle

uteke provenance

uteke supersede

uteke contradictions

uteke namespace

uteke tags

uteke recall — Advanced Flags

`--strategy graph` (Graph-augmented RAG)

AI-context output

Reading recall scores (#1405)

uteke room

Room consolidation notes (#1088)

uteke bench

uteke pin / unpin

uteke importance

uteke aging

uteke import

LLM fact extraction (`--extract`)

Scene-segmented output (#1009)

Batch import (`--batch-dir`)

uteke graph

uteke edges

Supported patterns

Usage

uteke rebuild-backlinks

uteke dream

Phases

uteke feedback

uteke orphans

uteke timeline

Other Commands

uteke-serve (Server Mode)

HTTP Endpoints

MCP Server

Document Commands (#406, #411, #438, #440)

`uteke doc create`

`uteke doc get`

`uteke doc list`

`uteke doc search`

`uteke doc update`

`uteke doc move`

`uteke doc delete`

`uteke doc export`

Graph API (#408, #542)

Visualization

Mutation

Server Authentication (#409)

Configurable Limits (#404)

Changelog

v0.6.5

v0.6.6