Skip to content

getting-started.md

Latest commit

 

History

History
188 lines (133 loc) · 5.52 KB

getting-started.md

File metadata and controls

188 lines (133 loc) · 5.52 KB
Raw
title Getting Started

Getting Started

Install

curl -fsSL https://raw.githubusercontent.com/codecoradev/uteke/main/install.sh | sh

See the Installation guide for all methods (Cargo, binary, Docker).

💡 First run downloads the embedding model (~188MB). No API keys needed.

Interactive Onboarding

New to uteke? Run the onboarding wizard — it detects your install, asks which AI agent you use, toggles features on/off, writes your config, and shows a full feature showcase:

uteke onboard

Non-interactive mode (use defaults, skip prompts):

uteke onboard --yes --agent hermes --namespace default

The wizard covers:

  1. Install detection — checks if uteke is on PATH and if a store exists
  2. Agent selection — Hermes, Claude, Cursor, Pi, or OpenCode
  3. Integration mode — manual tool (explicit calls) vs memory-provider (auto recall + extraction)
  4. Namespace — for multi-agent isolation
  5. Feature toggles — Aging, Auto-maintenance, Graph rerank, Salience/Recency boost, Server mode
  6. Config write — generates ~/.uteke/uteke.toml with your choices
  7. Agent init — runs uteke init --agent <your-choice> automatically
  8. Feature showcase — prints all uteke commands grouped by category

Your First Memory

# Store a memory with metadata enrichment
uteke remember --tags project "My app uses SvelteKit 5 with Tailwind" \
  --entity my-app --category frontend

# Hybrid search (vector + FTS5, ranked by RRF)
uteke recall "What frontend framework do I use?"

# Filter by entity or category
uteke recall "frontend" --entity my-app
uteke list --category frontend

# Text search with tag filter
uteke search "SvelteKit" --tags project

# List all memories
uteke list

# Check system health
uteke doctor

Tag Management

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

# Rename a tag across all memories
uteke tags rename old-name new-name

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

Multi-Agent Isolation

Each agent gets its own namespace. Memories never leak between agents:

# Agent "architect" stores its context
uteke --namespace architect remember "We chose PostgreSQL for ACID compliance"

# Agent "dev" has its own separate memory
uteke --namespace dev remember "Database connection string: postgres://localhost:5432/app"

# Each only sees its own memories
uteke --namespace architect recall "database"
uteke --namespace dev recall "database"

Recall Cache

The recall cache eliminates redundant embedding for repeated queries (~50ms savings). It's automatic — no configuration needed. Use --context for AI-prompt formatted output:

# AI-optimized context output
uteke recall "api design" --context

Export & Import

Port your memories anywhere:

# Export to JSONL (no embeddings — small, portable)
uteke export > memories.jsonl

# Import on another machine
uteke import memories.jsonl

# Import with LLM fact extraction (distills raw text into atomic facts)
uteke import notes.txt --extract

MCP Integration

Add uteke as an MCP server to your AI coding agent in seconds:

Claude Code — add to .mcp.json:

{ "mcpServers": { "uteke": { "command": "uteke-mcp" } } }

With HTTP (requires uteke-serve):

{ "mcpServers": { "uteke": { "url": "http://127.0.0.1:8767/mcp" } } }

See MCP Server for all supported clients and tools.

💡 Hermes users? Three integration modes available:

  • Mode C (shell hook): Lightest — automatic recall via pre_llm_call hook, no plugin/daemon needed. See Hermes integration.
  • Mode B (memory-provider): Full auto — uteke init --agent hermes --memory-provider. Automatic recall + LLM fact extraction.
  • Mode A (uteke-tool): Manual — uteke init --agent hermes. Explicit uteke(action="...") calls with multi-agent room support.

The install script installs all three binaries (uteke, uteke-serve, uteke-mcp) so MCP integration is available immediately.

Troubleshooting

If something goes wrong, uteke has built-in self-healing:

# Check system health (DB, index, model, consistency)
uteke doctor

# Verify DB and index consistency
uteke verify

# Repair index by rebuilding from SQLite
uteke repair

Where is Data Stored?

All data lives in ~/.uteke/:

~/.uteke/
├── uteke.db                    # SQLite (memories + metadata + FTS5)
├── uteke_index.usearch         # Persistent HNSW vector index
├── uteke_index.keys            # Index key mapping
├── embeddinggemma-q4/          # Local ONNX embedding model (~188MB)
│   └── onnx/                   # model_q4.onnx + model_q4.onnx_data
└── logs/
    ├── uteke.log               # Current log
    └── uteke.log.YYYY-MM-DD    # Rotated logs

Copy the entire folder to back up or transfer to another machine.

Next Steps