{"id":50471520,"url":"https://github.com/ajianaz/uteke","last_synced_at":"2026-06-01T11:00:43.525Z","repository":{"id":361053115,"uuid":"1252865556","full_name":"ajianaz/uteke","owner":"ajianaz","description":"🧠 The Brain for Your AI — Persistent memory \u0026 smart context management for AI agents. Rust, 2MB binary, zero config.","archived":false,"fork":false,"pushed_at":"2026-05-29T03:19:09.000Z","size":2767,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"develop","last_synced_at":"2026-05-29T03:22:05.603Z","etag":null,"topics":["ai","cli","embeddings","hnsw","local-first","memory","rust","sqlite","vector-database"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ajianaz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-29T00:27:31.000Z","updated_at":"2026-05-29T03:19:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ajianaz/uteke","commit_stats":null,"previous_names":["ajianaz/uteke"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ajianaz/uteke","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajianaz%2Futeke","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajianaz%2Futeke/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajianaz%2Futeke/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajianaz%2Futeke/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ajianaz","download_url":"https://codeload.github.com/ajianaz/uteke/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajianaz%2Futeke/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33771629,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","cli","embeddings","hnsw","local-first","memory","rust","sqlite","vector-database"],"created_at":"2026-06-01T11:00:17.532Z","updated_at":"2026-06-01T11:00:43.517Z","avatar_url":"https://github.com/ajianaz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Uteke-🧠-blue\" alt=\"Uteke\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eUteke\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\u003cstrong\u003eLocal-first memory for AI agents — written in Rust\u003c/strong\u003e\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/ajianaz/uteke/actions/workflows/ci.yml?branch=develop\"\u003e\u003cimg src=\"https://github.com/ajianaz/uteke/actions/workflows/ci.yml/badge.svg?branch=develop\" alt=\"CI\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/Apache-2.0\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-Apache_2.0-blue.svg\" alt=\"License: Apache 2.0\" /\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Rust-1.75+-orange.svg\" alt=\"Rust 1.75+\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/status-v0.0.4-green.svg\" alt=\"v0.0.4\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eFrom Javanese: \u003cstrong\u003euteke\u003c/strong\u003e (otak) = brain\u003c/em\u003e\n\u003c/p\u003e\n\n---\n\n## Quick Start\n\n```bash\n# Install\ngit clone https://github.com/ajianaz/uteke.git\ncd uteke\ncargo install --path crates/uteke-cli\n\n# Store a memory\nuteke remember \"Deploy v2.1 to staging on Friday\" --tags deploy,staging\n\n# Store in a specific namespace (multi-agent isolation)\nuteke --namespace hermes remember \"Prod server on AWS us-east-1\" --tags deploy\n\n# Semantic search (scoped to namespace)\nuteke --namespace hermes recall \"server deployment\"\n\n# Get stats\nuteke stats\n```\n\n**That's it.** No API keys. No server. No config. First run downloads the embedding model (~188MB) and you're good to go.\n\n\u003e 📖 For more install options (pre-built binaries, quick install script), see [INSTALL.md](INSTALL.md).\n\n---\n\n## Why Uteke?\n\nAI agents forget everything between sessions. Uteke gives them persistent, searchable memory — entirely local.\n\n| | **Uteke** | MemGPT | ChromaDB | Zep |\n|---|---|---|---|---|\n| **Setup** | Single binary | Python + deps | Python + server | Cloud service |\n| **Cloud required** | ❌ No | ❌ No | ✅ Optional | ✅ Yes |\n| **Semantic search** | ✅ Built-in | ✅ | ✅ | ✅ |\n| **Embedding model** | Built-in (ONNX) | External | External | External |\n| **Zero config** | ✅ | ❌ | ❌ | ❌ |\n| **Offline** | ✅ Fully | ⚠️ Partial | ⚠️ Partial | ❌ |\n| **Language** | Rust | Python | Python | Go + Python |\n| **Binary size** | Small | Large | Large | N/A |\n| **License** | Apache 2.0 | Apache 2.0 | Apache 2.0 | MIT |\n\n---\n\n## Use Cases\n\n- **🤖 AI Agents** — Give your agents persistent memory across sessions. Recall context from yesterday's conversation.\n- **🔬 Research Notes** — Store findings with semantic search. Find that insight you read 3 months ago.\n- **📝 Personal Knowledge** — A local, searchable second brain. No cloud, no subscriptions, no lock-in.\n- **🛠️ Developer Context** — Remember architecture decisions, debug notes, and project-specific knowledge.\n\n---\n\n## Commands\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `remember` | Store a new memory with optional tags | `uteke remember \"text\" --tags a,b` |\n| `recall` | Semantic search using vector similarity | `uteke recall \"query\" --limit 5` |\n| `search` | Keyword text search (supports `--tags` filter) | `uteke search \"monorepo\" --tags rust,cli` |\n| `list` | List memories with pagination and tag filter | `uteke list --tag project --limit 20 --offset 10` |\n| `get` | Get a single memory by ID | `uteke get \u003cuuid\u003e` |\n| `forget` | Delete a memory by ID, tag, tier, or all | `uteke forget \u003cuuid\u003e`, `uteke forget --tag stale` |\n| `consolidate` | Find and merge duplicate memories | `uteke consolidate --threshold 0.60 --dry-run` |\n| `prune` | Remove deprecated/expired temporal memories | `uteke prune --ttl 30 --dry-run` |\n| `namespace list` | List all namespaces with counts | `uteke namespace list` |\n| `namespace switch` | Set default namespace in config | `uteke namespace switch my-agent` |\n| `tags list` | List all tags with usage counts | `uteke tags list --by-count` |\n| `tags rename` | Rename a tag across all memories | `uteke tags rename old-name new-name` |\n| `tags delete` | Delete a tag from all memories | `uteke tags delete unused-tag` |\n| `aging status` | Show hot/warm/cold/never-accessed breakdown | `uteke aging status` |\n| `aging preview` | Preview memories older than N days | `uteke aging preview --days 90` |\n| `aging cleanup` | Delete stale memories older than N days | `uteke aging cleanup --days 180 --confirm` |\n| `stats` | Show memory store statistics (with tier breakdown) | `uteke stats` |\n| `doctor` | Check system health (DB, index, model, consistency) | `uteke doctor` |\n| `verify` | Verify DB and index consistency | `uteke verify` |\n| `repair` | Rebuild index from SQLite | `uteke repair` |\n| `hook install` | Install shell hook for auto-context loading | `uteke hook install bash` |\n| `completions` | Generate shell completion scripts | `uteke completions bash` |\n\n### Global Flags\n\n| Flag | Description |\n|------|-------------|\n| `--store \u003cpath\u003e` | Override store location (default: `~/.uteke`) |\n| `--namespace \u003cname\u003e` | Namespace for multi-agent isolation (default: `\"default\"`) |\n| `--config \u003cpath\u003e` | Override config file path |\n| `--json` | Output as JSON (all commands) |\n| `--verbose` | Enable debug logging |\n\n### JSON Output\n\nEvery command supports `--json` for machine-readable output:\n\n```bash\nuteke remember \"hello\" --json\n# {\"id\":\"a1b2c3d4-...\"}\n\nuteke recall \"hello\" --json\n# [{\"memory\":{\"id\":\"...\",\"content\":\"hello\",...},\"score\":0.95}]\n\nuteke stats --json\n# {\"total_memories\":42,\"unique_tags\":5,\"db_size_bytes\":102400}\n```\n\n### Server Mode\n\nStart a persistent HTTP server for fast AI agent access (21ms vs 980ms cold start):\n\n```bash\n# Start server\nuteke-serve --port 8767\n\n# Enable auto-routing in config\n# [server]\n# enabled = true\n\n# CLI commands now route via HTTP automatically\nuteke recall \"what was that context?\"  # 21ms!\nuteke remember \"New finding\" --tags research\n```\n\n### Multi-Agent Namespaces\n\nIsolate memories per agent using `--namespace`:\n\n```bash\n# Each agent gets its own memory space\nuteke --namespace hermes remember \"Prod deploy config\" --tags deploy\nuteke --namespace pi remember \"User prefers dark mode\" --tags pref\n\n# Search is scoped to the namespace\nuteke --namespace hermes recall \"deployment\"  # Only finds hermes memories\nuteke --namespace pi recall \"preferences\"    # Only finds pi memories\n\n# Without --namespace, uses \"default\" namespace\nuteke remember \"General knowledge\" --tags misc\n```\n\nExisting databases are auto-migrated — the `namespace` column is added on first run with zero data loss.\n\n---\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────┐\n│                    CLI (clap)                        │\n│  uteke-cli crate — auto-routes to server if running │\n├─────────────────────────────────────────────────────┤\n│              HTTP API (uteke-serve)                  │\n│  /health /remember /recall /search /list /forget    │\n│  /stats /namespaces — CORS enabled, ~21ms recall    │\n├─────────────────────────────────────────────────────┤\n│                    Uteke API                         │\n│          uteke-core crate (lib)                      │\n├──────────┬──────────────────┬────────────────────────┤\n│   ONNX   │     usearch      │       SQLite           │\n│ Embedding│  Vector Index    │    Metadata Store      │\n│ (256d)   │ (Persistent HNSW)│    (rusqlite)          │\n├──────────┴──────────────────┴────────────────────────┤\n│              ~/.uteke/ (local storage)               │\n│ uteke.db │ uteke_index.usearch │ models/embeddinggemma/ │\n└─────────────────────────────────────────────────────┘\n```\n\n| Component | Technology | Detail |\n|-----------|-----------|--------|\n| Language | Rust (no unsafe) | Memory-safe, fast, single binary |\n| Vector Index | usearch | Persistent HNSW with incremental updates |\n| Storage | SQLite (rusqlite) | Embedded, zero-config, battle-tested |\n| Embedding | EmbeddingGemma Q4 ONNX | 256d vectors, multilingual, downloaded on first run |\n| Namespaces | SQLite column | Multi-agent isolation, zero overhead |\n| Tiered Memory | Access tracking | Hot/Warm/Cold scoring boost |\n| CLI | clap | Standard Rust CLI framework |\n\n**How it works:**\n1. `remember` → text is embedded into a 256d vector via ONNX → stored in SQLite + indexed in usearch\n2. `recall` → query is embedded → usearch finds nearest neighbors → hot memories get +0.1 score boost → returns ranked results\n3. `search` → SQLite LIKE-based keyword search (fast, deterministic, scoped to namespace)\n4. `forget` → incremental delete from usearch + SQLite (no rebuild)\n5. Everything lives in `~/.uteke/` — fully local, fully yours\n\n---\n\n## Python Integration\n\nUteke comes with a zero-dependency Python wrapper (stdlib only, Python 3.8+):\n\n```python\nfrom python_hermes import UtekeMemory\n\nmem = UtekeMemory()\n\n# Store\nmid = mem.remember(\"Deploy v2.1 to staging\", tags=[\"deploy\", \"staging\"])\n\n# Semantic search\nresults = mem.recall(\"deployment steps\")\nfor r in results:\n    print(f\"[{r['score']:.2f}] {r['memory']['content']}\")\n\n# Forget\nmem.forget(mid)\n```\n\nThe wrapper calls the `uteke` binary via subprocess with `--json` — no FFI, no bindings, works everywhere.\n\nSee [`examples/python_hermes.py`](examples/python_hermes.py) for the full implementation.\n\n---\n\n## Shell Completions\n\n```bash\nuteke completions bash  \u003e ~/.local/share/bash-completion/completions/uteke\nuteke completions zsh   \u003e ~/.zfunc/_uteke\nuteke completions fish  \u003e ~/.config/fish/completions/uteke.fish\n```\n\n---\n\n## Configuration\n\nUteke supports `uteke.toml` configuration with layered resolution:\n\n1. `./uteke.toml` (current directory)\n2. Parent directories up to root\n3. `~/.config/uteke/uteke.toml` (user-level)\n4. Built-in defaults\n\n```toml\nstore_path = \"~/.uteke\"\nlog_level = \"info\"\nlog_dir = \"~/.uteke/logs\"\ndefault_namespace = \"default\"\n```\n\nOverride config file path with `--config`:\n\n```bash\nuteke --config ./my-config.toml remember \"project-specific note\"\n```\n\n---\n\n## Development\n\n```bash\n# Build\ncargo build --workspace\n\n# Test\ncargo test --workspace\n\n# Lint\ncargo clippy --workspace --all-targets -- -D warnings\ncargo fmt --all -- --check\n\n# Run locally\ncargo run --bin uteke -- remember \"test\" --tags dev\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the full contribution guide.\n\n---\n\n## Roadmap\n\nUteke follows a demand-gated roadmap — we build what people actually use.\n\n**Now (v0.0.4):** Server mode (21ms warm recall), contradiction detection, consolidation, bulk operations, namespace switching, CLI auto-routing to server\n**Phase A (100+ stars):** Better embeddings, import from external sources, Hermes plugin, benchmark\n**Phase B (500+ stars):** Python SDK (PyO3), Node.js SDK, editor integrations\n**Phase C (1000+ stars):** Team features, cloud sync (opt-in), knowledge graph\n\nSee the [full blueprint](BLUEPRINT_V2.md) for details.\n\n---\n\n## License\n\n[Apache License 2.0](LICENSE) — use it, fork it, ship it.\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eLocal-first. Zero config. Your memory, your machine.\u003c/strong\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajianaz%2Futeke","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fajianaz%2Futeke","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajianaz%2Futeke/lists"}