Uteke Memory

Uteke Memory Skill

Persistent memory engine for AI agents via the uteke CLI. Version: 0.18.2 — SQLite + usearch HNSW + FTS5 hybrid search (RRF k=60); fusion (weighted RRF of the vector and hybrid rankings) is the default recall strategy since 0.16.0. Zero unsafe code.

This skill ships with each release — its version tracks the CLI version (a CI gate fails when they drift, see skill-version-parity test). If this file is older than your uteke --version, run uteke init again or re-read the docs for the current release.

Hermes integration: Install the uteke-memory plugin for automatic recall on every turn via the pre_llm_call hook. No shell hook or daemon needed. See extensions/hermes-uteke-memory/ for the plugin source. Manual tool calls via uteke-tool plugin remain available for explicit remember/forget/room operations.

Global Flags (all commands)

Commands

Core Memory Operations

Documents (Wiki / Knowledge Base)

Knowledge Graph

Memory Relationships

Rooms (Collaborative Memory)

Pinning & Importance

Maintenance

Tags & Namespaces

Memory Aging

Health, Stats & Data

Stale-index symptom (pitfall 0g): a memory is recallable via --strategy fts5 but missing under the default fusion/hybrid — that is a vector-index desync, not data loss. Run uteke verify, then uteke repair. On uteke-serve, use POST /verify / POST /repair (HTTP) or the uteke_verify / uteke_repair MCP tools — no restart needed. Run verify after every serve upgrade (#1245 class: CLI upgraded, serve left behind → index written by the old binary reads as mismatched).

Search strategy guide — filters, not silos:

• namespace = agent/workspace identity — pass it explicitly on recall.
• room = collaborative discussion context (uteke room recall).
• tags (e.g. project:<repo>) = the primary project filter.
• Strategies: fusion (default), hybrid (RRF vector+FTS5), fts5 (keyword — best for short 1–3 word queries and exact terms), vector (pure semantic), graph. Scores are rank-based (RRF), not cosine — don't threshold them like similarity; use recall --explain for the real vector similarity.
• Prefer 2–3 core keywords: FTS5 AND-matches all tokens, long natural sentences can zero out the keyword arm.

Import / Export / Bench

Setup & Upgrade

Architecture

• Storage: SQLite (WAL mode) with namespace column + FTS5 virtual table
• Vector index: usearch persistent HNSW (768d, cosine similarity)
• Hybrid search: RRF (k=60) merges vector + FTS5 results; graph strategy adds graph-signal reranking
• Fusion (default since 0.16.0): weighted RRF of the vector and hybrid rankings — LongMemEval 500Q R@5 0.946
• Embedding: ONNX EmbeddingGemma Q4 (768d), auto-downloaded
• Tiered memory: Hot (<7d, +0.1 boost), Warm (<30d), Cold (>30d)
• Schema versioning: Integer counter, auto-migration on upgrade
• Zero unsafe code (unsafe_code = "forbid")
• Project-scoped stores: uteke --store .uteke remember "..."

Usage Patterns

Session lifecycle

uteke recall "project architecture decisions" --namespace pi-agent
uteke remember "Use WAL mode for concurrent reads" --tags architecture,db --entity db-layer
uteke recall "last session state" --namespace pi-agent

Metadata-enriched storage

uteke remember "Deploy staging to AWS us-east-1" \
  --tags deploy,aws --entity staging-server --category infrastructure \
  --source "meeting-notes.md" --source-type file

Time-travel queries

uteke recall "auth flow" --at 2026-06-01T12:00:00Z
uteke list --at 2026-06-01T12:00:00Z

Graph-enhanced recall

uteke recall "database design" --strategy graph --related --depth 2
uteke graph neighbors "auth-service" --depth 3
uteke graph path "api-gateway" "database"

Document wiki

uteke doc create architecture/overview --title "Architecture Overview" --file overview.md --parent docs
uteke doc search "authentication" --mode hybrid
uteke doc list --tree

Room collaboration

uteke remember "Decision: use PostgreSQL" --room design-review --author alice
uteke room recall design-review --query "database"
uteke room summary design-review

Programmatic (JSON)

uteke recall "auth flow" --json --limit 3
uteke stats --json
uteke list --tag architecture --json --limit 50

Maintenance pipeline

uteke dream                           # Full pipeline
uteke dream --phases lint,verify --dry-run  # Selective, safe
uteke importance                      # Recompute scores
uteke orphans --threshold 0.2         # Find disconnected

Project-Aware Memory (MANDATORY)

Always tag memories with project:<name> when working in a project. This prevents noise when recalling — you only see memories relevant to the current project.

How to detect the project name

1. From workdir / cwd — extract the repo folder name:
   • /home/user/repos/bond/ → project:bond
   • /home/user/repos/uteke/ → project:uteke
   • /home/user/repos/my-saas-app/ → project:my-saas-app
2. From file paths mentioned in the conversation
3. From the project name the user mentions

Rules

Examples

# Working on the "bond" project
uteke recall "auth flow" --tags project:bond
uteke remember "JWT rotation implemented with refresh tokens" --tags project:bond,decision,auth
uteke remember "DB schema uses UUID v7 for primary keys" --tags project:bond,architecture,db

# Working on the "uteke" project
uteke recall "vector index corruption" --tags project:uteke
uteke remember "Fixed usearch rebuild race condition" --tags project:uteke,bugfix,index

# General conversation — no project tag
uteke remember "User prefers concise responses" --tags preference

# Cross-project recall (explicitly requested)
uteke recall "shared auth pattern" --tags project:bond,project:corin

Why this matters

Without project tags, memories from all projects mix together. When you recall "fix auth bug" while working on project Bond, you might get results from project Corin's auth system — causing confusion and wasted context. Project tags ensure recall is scoped and noise-free.

When to Use

Hermes Auto-Recall Plugin

The uteke-memory plugin registers a pre_llm_call hook that automatically recalls relevant memories on every turn and injects them into the user message. No shell hook, no daemon required (subprocess transport). Supports HTTP transport to uteke-serve for container deployments.

# Generate and install the plugin
uteke init --agent hermes
# → writes to ~/.hermes/plugins/uteke-memory/

# Enable in config.yaml
# plugins:
#   enabled:
#     - uteke-memory

Config via ~/.hermes/uteke.json or env vars: UTEKE_BIN, UTEKE_NAMESPACE, UTEKE_SERVER_URL, UTEKE_TOKEN, UTEKE_RECALL_LIMIT (default 5), UTEKE_RECALL_MIN_SCORE (default 0.40).

Server Mode (uteke-serve)

HTTP daemon with REST API for all operations + monitoring/maintenance endpoints.

uteke-serve --port 8767
# CLI auto-routes to server when running: ~42ms recall vs ~3s cold start

Endpoints mirror CLI commands (e.g., POST /remember, POST /recall). Supports read-only API tokens for restricted access.