koala-rust
Local, private memory for AI agents. One small binary that speaks MCP over stdio. Versioned facts, semantic recall, knowledge graph, tasks, handoff notes, sync and WASM plugins. Data stays in a SQLite file on your machine.
Status (v0.3.4): useful for pilots and personal or team agent memory. Not yet ready for regulated production data. There is no encryption at rest, no access control, no tamper-evident audit log and no certification. See Readiness and the open issues. Every number below was measured on the v0.3.3 Linux x86_64 release binary on 22 Nov 2026 unless marked otherwise.
Try it in two minutes
# 1. download the self-contained bundle (Linux x86_64 shown)
gh release download -R dbillion/koala-rust -p 'koala-rust-x86_64-unknown-linux-gnu.tar.gz' -p SHA256SUMS.txt
sha256sum -c --ignore-missing SHA256SUMS.txt
tar -xzf koala-rust-x86_64-unknown-linux-gnu.tar.gz
chmod +x koala-rust
# 2. CLI: versioned facts (uses a throwaway state dir, your real ~/.koala is untouched)
sh examples/cli_demo.sh ./koala-rust
# 3. MCP + semantic recall, with one health and one finance sample (needs python3, no packages)
python3 examples/demo.py ./koala-rust
Expected output of step 3 (made-up sample data):
MCP tools: 60
stored health/cardio 1.14s <- first call loads the model
Q: which medicines are unsafe with blood thinners
-> health/cardio: Patient on warfarin, avoid NSAIDs due to bleeding risk
Q: which companies can traders not touch
-> finance/desk: Equity desk restricted list includes ACME Corp until merger closes
Process memory: 52 MB
The question and the stored text share no key words. The match comes from local embeddings.
Use it from Claude Desktop, Claude Code, Cursor or any MCP client:
{ "mcpServers": { "koala": { "command": "/path/to/koala-rust", "args": ["--serve"] } } }
Space it takes
| Item | Measured |
|---|---|
| Binary | 14.9 MB (macOS arm64), 16.3 MB (Windows), 21.5 MB (Linux arm64), 24.4 MB (Linux x86_64) |
| Memory, server idle | 18 MB |
| Memory, after embedding model is loaded | 52 MB |
| Embedding model (one-time download from Hugging Face) | about 30 MB (potion-base-8M, 256 dimensions) |
| Database with 3 facts and vector tables | about 1.2 MB (184 KB without vector tables) |
| Write plus embed, after model load | about 10 ms |
| Semantic recall on a 3-fact store | about 20 to 40 ms |
| Needs network after the model is cached | No. Verified by running the demo under unshare -n |
Not measured: large stores. Benchmarks at 1k, 10k and 100k facts are still to do.
Where the gap is
Most agent memory products are cloud services or need a vector or graph database next to them. Some run a language-model call on every write. koala-rust is a different trade:
- One file to run, one file of data. No Postgres, no Neo4j, no vector service.
- No language-model call on write. Embeddings come from a small local static model, so writes are fast and have no per-write token cost.
- Exact history. Every change to a fact is a numbered version with a timestamp.
- Speaks MCP natively. 60 tools, works with agents you already use.
Be honest about the limits: “local and offline” alone is not unique (see table). The aim is to be the smallest local option and, once the issues below land, the one with provable history, verified deletion and a tamper-evident audit trail.
Comparison with current tools
Competitor facts come from vendor pages and comparison blog posts gathered in Nov 2026. They are not independently verified. Check prices and claims before you decide.
| koala-rust | Mem0 | Letta | Zep / Graphiti | Cognee | Dakera | |
|---|---|---|---|---|---|---|
| Shape | Single binary, SQLite | Library plus cloud | Full agent runtime | Temporal knowledge graph | Graph pipeline | Single Rust binary |
| License | MIT | Apache 2.0 | Apache 2.0 | Graphiti Apache 2.0, Zep cloud closed | Apache 2.0 | MIT open-core |
| Offline / air-gapped | Yes, once model cached | Limited, needs local LLM setup | Yes | Library only, needs graph DB | Yes | Yes |
| Extra services to run | None | Vector DB for self-host | Postgres or SQLite | Neo4j, FalkorDB or Neptune | Optional graph/vector DBs | None |
| Write path | Local embedding only | LLM extraction per add | LLM tool calls | Graph extraction | Multi-stage LLM pipeline | Local embedding |
| Footprint | 15 to 24 MB binary, 18 to 52 MB RAM | Not stated | Not stated | Not stated | Not stated | about 101 MB binary |
| Encryption at rest | No | Not stated | Not stated | Cloud | Yes (stated) | AES-256-GCM (stated) |
| Compliance claims | None | SOC 2 Type I, “HIPAA ready” | Enterprise SSO | SOC 2 Type II, HIPAA BAA (cloud) | GDPR-oriented | Not stated |
| List price (managed) | Free | $19 to $249 / month | $20 / month and usage | $125 to $375 / month | usage based | No cloud |
What it is worth in money
Honest version: today the direct, countable saving is software fees you stop paying. It is real but modest. The larger value (selling into regulated teams) depends on the open issues.
Managed memory list prices, per workspace (Nov 2026 research, verify before relying on them):
| Service and plan | Per month | Per year |
|---|---|---|
| Mem0 Starter / Pro | $19 / $249 | $228 / $2,988 |
| Zep Flex / Flex Plus | $125 / $375 | $1,500 / $4,500 |
| Letta Pro | $20 | $240 |
| koala-rust | $0 licence | $0 licence, you pay for your own machine |
So a team running one workspace avoids roughly $0.2k to $4.5k a year at list price. Savings grow with the number of workspaces and agents.
Second saving, not quantified: services that call a language model on every write
(Mem0, Cognee, Zep ingestion) add a token cost per write. koala-rust does not.
Estimate for your own load: writes per month x your cost of one extraction call.
What this does not save you. koala-rust does not reduce compliance cost. If your company needs SOC 2 or a HIPAA programme, budget for it yourself. Rough small-vendor ranges from the same research: SOC 2 audit $3k to $40k, compliance platform $7.5k to $20k a year, penetration test $5k to $15k, HIPAA risk assessment $2k to $5k, about $25k to $80k+ in year one. Not legal advice.
Where larger value could come from, once the work is done: keeping agent memory inside your own network can shorten the vendor-review step in health and finance, because no third party holds the data. That only holds if you can show encryption, access control, deletion and audit, which are the open issues.
Readiness for health, finance and defense
| Capability | Status | Tracking |
|---|---|---|
| Runs fully on your own machine, no cloud | Works (model cached once) | #18 for first-run download |
| Semantic recall, version history | Works | |
| Verified deletion of a fact and all its versions | Broken, old versions and bytes stay | #11 |
| Retention rules (TTL) | Missing | #12 |
| “What did the agent know on date X” | Missing | #13 |
| Encryption at rest | Missing | #14 |
| Tamper-evident audit log | Missing | #15 |
| Who can read what (labels, namespaces) | Missing | #16 |
| Signed and sandboxed plugins | Partial. The built-in hash-tools demo fails | #17, #29 |
| HIPAA, SOC 2, FedRAMP, CMMC | None. These apply to organisations, not binaries | #24 |
Healthcare
- Today: fine for pilots with de-identified or synthetic data, or inside a machine you already encrypt and control. Do not store patient identifiers yet.
- Why it fits: data never leaves the hospital machine, and recall works from meaning (“unsafe with blood thinners”).
- Needed first: verified delete (#11), retention, encryption, audit, access labels. Guide: #25. Whether you need a business associate agreement depends on who hosts and who can reach the data. Ask a health-privacy lawyer.
Finance
- Today: fine for analyst or advisor copilots on non-sensitive notes, and for personal use. Do not store material non-public information yet.
- Why it fits: local data, exact version history, no per-write model cost.
- Needed first: namespaces for information barriers (#16), point-in-time recall (#13), audit chain (#15). A hash chain alone is not SEC 17a-4 or WORM compliance. Pair with storage that holds that certification. Guide: #26.
Defense and intelligence (last)
- Today: not suitable. The offline story is partly there, but buyers expect FIPS-validated cryptography, TPM or HSM keys, SBOMs, CMMC and accreditation, and often certified hardware.
- Realistic route: small embedded memory for edge devices through hardware partners and prime integrators, after the health and finance work. Track: #27.
Where help is wanted
| Area | Issues |
|---|---|
| Data protection | #11 delete bug, #12 retention, #14 encryption |
| Trust and audit | #13 as-of recall, #15 audit log, #16 access, #17 plugin trust, #29 plugin bug |
| Offline and ops | #18 offline build, #20 migrations and backup |
| Code health | #19 split large files, #21 errors and tests |
| Usability | #22 CLI recall, #23 Python adapters |
| Docs and sector guides | #24, #25, #26, #27 |
Reference guide
The original README content, kept in full. Where v0.3.3 behaves differently, the text is corrected or a Reality check note is added.
✨ Features
| Feature | Description |
|---|---|
| Persistent Facts | Versioned key-value storage with SQLite |
| Semantic Search | Exact KNN vector search via sqlite-vec (256-dim embeddings) |
| Real Embeddings | Local Model2Vec + potion-base-8M (256-dim, ~30 MB, downloads from Hugging Face once on first use) |
| Knowledge Graph | Entities, observations, relations with graph traversal |
| Task Management | Structured tasks/notes with queries and updates |
| CRDT Sync | Vector clocks + last-write-wins for multi-agent collaboration |
| WASM Plugins | Sandboxed plugins (wasmtime) + native plugins (libloading) |
| Plugin Marketplace | Install plugins. SHA256 checksum is checked when the registry lists one. No signatures yet (#17) |
| MCP Server | 60 tools via stdio — works with Claude, Hermes, any MCP client |
🏛️ Architecture Overview
flowchart TB
subgraph Agent["AI Agent (Claude, Hermes, Custom)"]
direction TB
MCP_CLIENT[MCP Client]
end
subgraph Server["koala-rust MCP Server (stdio)"]
direction TB
MCP_HANDLER[MCP Handler 60 tools]
subgraph Core["Core Services"]
FACTS[Fact Store<br/>SQLite + versions]
ENTITIES[Entity Graph<br/>Observations + Relations]
TASKS[Task Manager<br/>CRUD + Queries]
NEURAL[Neural Model<br/>Online Learning]
end
subgraph Vector["Vector Engine"]
SQLITE_VEC[(sqlite-vec exact KNN)]
EMBEDDINGS[Model2Vec + potion-base-8M]
end
subgraph Sync["CRDT Sync"]
VECTOR_CLOCK[VectorClock<br/>Last-Write-Wins]
PEER_SYNC[Peer Sync Protocol]
end
subgraph Plugins["Plugin System"]
WASM_RUNTIME[wasmtime<br/>WASM Sandbox]
NATIVE_LOADER[libloading<br/>Native Plugins]
MARKETPLACE[Plugin Registry<br/>SHA256 Verify]
end
end
subgraph Storage["Local Storage (~/.koala)"]
KOALA_DB[(koala.db)]
MODEL_DIR[model/]
PLUGIN_DIR[plugins/<br/>wasm/ + native/]
REGISTRY[registry.json]
end
MCP_CLIENT <-->|JSON-RPC 2.0<br/>stdio| MCP_HANDLER
MCP_HANDLER --> FACTS
MCP_HANDLER --> ENTITIES
MCP_HANDLER --> TASKS
MCP_HANDLER --> NEURAL
MCP_HANDLER --> Vector
MCP_HANDLER --> Sync
MCP_HANDLER --> Plugins
FACTS --> KOALA_DB
ENTITIES --> KOALA_DB
TASKS --> KOALA_DB
NEURAL --> MODEL_DIR
Vector --> SQLITE_VEC
Vector --> EMBEDDINGS
Sync --> VECTOR_CLOCK
Sync --> PEER_SYNC
Plugins --> WASM_RUNTIME
Plugins --> NATIVE_LOADER
Plugins --> MARKETPLACE
Plugins --> PLUGIN_DIR
MARKETPLACE --> REGISTRY
SQLITE_VEC --> KOALA_DB
EMBEDDINGS -->|~30 MB, first run| MODEL_DIR
style Agent fill:#e3f2fd
style Server fill:#fff3e0
style Storage fill:#e8f5e9
style Vector fill:#fce4ec
style Sync fill:#f3e5f5
style Plugins fill:#fff8e1
🚀 Quick Start
Install (Self-contained release bundle)
Choose the archive matching your platform from GitHub Releases. Each archive contains the Koala executable and its matching sqlite-vec loadable extension (vec0.so, vec0.dylib, or vec0.dll). v0.3.3 and earlier do not include these bundles; for those versions, install a compatible extension separately and set KOALA_VEC0_PATH.
| Platform | Release archive |
|---|---|
| Linux x86_64 | koala-rust-x86_64-unknown-linux-gnu.tar.gz |
| Linux ARM64 | koala-rust-aarch64-unknown-linux-gnu.tar.gz |
| macOS Intel | koala-rust-x86_64-apple-darwin.tar.gz |
| macOS Apple Silicon | koala-rust-aarch64-apple-darwin.tar.gz |
| Windows x86_64 | koala-rust-x86_64-pc-windows-msvc.tar.gz |
Example for Linux x86_64:
curl -fL https://github.com/dbillion/koala-rust/releases/latest/download/koala-rust-x86_64-unknown-linux-gnu.tar.gz -o koala-rust.tar.gz
curl -fL https://github.com/dbillion/koala-rust/releases/latest/download/SHA256SUMS.txt -o SHA256SUMS.txt
sha256sum -c --ignore-missing SHA256SUMS.txt
tar -xzf koala-rust.tar.gz
chmod +x koala-rust
./koala-rust --serve
Keep the executable and its adjacent vec0.* library together. For source/Cargo installs, install a compatible sqlite-vec extension separately and set KOALA_VEC0_PATH to its full path:
cargo install --git https://github.com/dbillion/koala-rust
Run MCP Server
# Set state directory (where SQLite + embeddings live)
export KOALA_STATE_DIR=~/.koala
# Start MCP server (stdio)
./koala-rust --serve
Use with Any MCP Client
Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"koala": {
"command": "/full/path/to/koala-rust",
"args": ["--serve"],
"env": { "KOALA_STATE_DIR": "/home/you/.koala" }
}
}
}
Hermes (~/.hermes/config.yaml):
mcp_servers:
koala-rust:
command: "/full/path/to/koala-rust"
args: ["--serve"]
env:
KOALA_STATE_DIR: "/home/you/.koala"
enabled: true
Custom Client — connect via stdio JSON-RPC 2.0.
🎯 10 Key Business Use Cases
| # | Use Case | Value |
|---|---|---|
| 1 | Institutional Knowledge Retention | Never lose technical decisions, debugging context, or tribal knowledge when team members leave. Semantic search finds “why we chose X” instantly. |
| 2 | Multi-Agent Collaboration | Research, coding, and review agents share a synchronized fact base via CRDT — no conflicting states, no manual handoffs. |
| 3 | Compliance & Audit Trail | Versioned facts + timestamps = immutable record of decisions. Export for SOC2, GDPR, or internal audits. |
| 4 | Cross-Session Continuity | Agents resume exactly where they left off — context, tasks, learned patterns persist across restarts, days, machines. |
| 5 | Private AI Memory (Air-Gapped) | 100% local, no API keys, no cloud. Runs in secure environments, regulated industries, offline deployments. |
| 6 | Plugin-Driven Workflow Automation | Install WASM plugins for custom transformers (hash, JSON, text, domain-specific). Extend without recompiling. |
| 7 | Semantic Search over Conversations | “What did we decide about auth last month?” → vector search returns relevant turns, not keyword matches. |
| 8 | Knowledge Graph for Domain Modeling | Entities + observations + relations = queryable domain model. “Show all services depending on PostgreSQL.” |
| 9 | Task Handoff Between Agents | Structured tasks with state, priority, assignee. Agent A creates, Agent B picks up, Agent C reviews — all tracked. |
| 10 | Embedding-Powered RAG Without Cloud | Local embeddings + vector search = full RAG pipeline on-device. Zero marginal cost per query. |
Reality check (v0.3.3) for use cases 3 and 5.
- #3 Compliance & audit trail. Versions and timestamps are a history, not an immutable record. Rows can be edited, and
fact-deleteleaves old versions and bytes on disk (#11). There is no hash chain or signature yet (#15). Do not present it to an auditor as tamper-evident. Nothing here is certified for SOC 2 or HIPAA.- #5 Air-gapped. Works offline once the embedding model is cached. The first run downloads it, and plugin registry commands fetch from GitHub (#18). The database file is not encrypted (#14).
🛠️ CLI Usage
# Health check
koala-rust health
# Facts
koala-rust fact-write --name "project:config" --text "Uses port 8080"
koala-rust fact-read --name "project:config"
koala-rust fact-list
koala-rust fact-versions --name "project:config" --limit 5
# Entities & Knowledge Graph
koala-rust entity-create --name "User" --type "person" --observations "Prefers TypeScript"
koala-rust entity-search --query "User"
koala-rust entity-create --name "Project" --type "project"
koala-rust relation-create --from "User" --to "Project" --type "owns"
# Tasks
koala-rust task-create --title "Review PR #42" --body "Check vector search logic"
koala-rust task-query --status pending
# Embeddings & Vector Search
koala-rust embed-text --text "How to configure vector search"
koala-rust vector-upsert-fact --fact-id 1 --embedding "0.1,0.2,..." # comma list; see #22
koala-rust vector-search-facts --query-embedding "0.1,0.2,..." --k 5
# Sync (Multi-agent)
koala-rust sync-status
koala-rust sync-push
koala-rust sync-pull
# sync_write_fact, sync_get_changes and sync_merge_changes are MCP tools
# Plugins
# plugin_list is an MCP tool; the CLI has plugin-search / install / uninstall / call
koala-rust plugin-search --query "hash"
koala-rust plugin-install --name hash-tools
# Flags are --plugin --tool --args. This hash-tools example currently fails in v0.3.3, see #29
koala-rust plugin-call --plugin hash-tools --tool sha256 --args '{"input":"hello"}'
# Continuity (handoff notes, decisions, project status)
koala-rust context bootstrap --project myproject
koala-rust context checkpoint --help
koala-rust context decision --help
koala-rust context status --help
Commands above were checked against
koala-rust --helpof v0.3.3. Semantic recall (recall,remember_semantic) is MCP-only for now (#22).
🔌 MCP Tools (60 Total)
| Category | Tools |
|---|---|
| Health | health |
| Facts | write_fact, read_fact, list_facts, read_fact_versions, delete_fact, delete_fact_prefix |
| Entities | create_entities, add_observations, open_nodes, search_nodes, create_relations |
| Tasks | create_task_or_note, query_tasks, update_task |
| Neural Model | model_init, model_train, model_predict, model_status, feedback, explain_rank, sequential_thinking, conclusion, thought_history, thought_reset, model_save, model_load |
| Vector Search | vector_upsert_fact, vector_upsert_entity, vector_search_facts, vector_search_entities, vector_delete_fact, vector_delete_entity |
| Sync (CRDT) | sync_write_fact, sync_read_fact, sync_list_facts, sync_create_entity, sync_get_changes, sync_merge_changes |
| Semantic memory | remember_semantic, recall, reindex_facts |
| Continuity | bootstrap_context, create_handoff, get_project_context, get_user_context, record_decision, search_memory, update_project_status |
| Embeddings | embed_text, embed_batch |
| Plugins | plugin_load, plugin_call, plugin_list, plugin_discover |
| Marketplace | plugin_search, plugin_install, plugin_uninstall, plugin_registry_stats, plugin_update_registry |
📚 koala-mcp Skill (Usage Guide)
A dedicated skill teaches agents how to use koala-rust effectively via MCP. Included in this repo at skills/koala-mcp/.
Install Skill
# Hermes (from local repo)
hermes skill install skills/koala-mcp
# Or clone skill dir directly
cp -r skills/koala-mcp ~/.hermes/skills/koala-mcp
Skill Provides
| Capability | Description |
|---|---|
| Tool Reference | All 50 MCP tools with parameters, examples, error handling |
| Workflow Patterns | Common patterns: fact extraction → embed → upsert → search |
| Best Practices | When to use facts vs entities vs tasks, naming conventions |
| Integration Recipes | Claude Desktop, Hermes, custom MCP clients |
| Troubleshooting | Common errors, performance tuning, debugging tips |
Example Skill Usage (Agent)
# Agent reads skill, then:
koala_recall("authentication architecture decision")
# → Returns relevant facts with scores
koala_write_fact("api:rate_limit", "100 req/min per IP")
# → Stores with auto-embedding for future recall
🧠 Auto-Conversation Memory (Hermes)
The koala-memory Hermes plugin captures every conversation turn, extracts facts, generates embeddings, and enables semantic recall.
Install Plugin
# Copy to Hermes user plugins dir
cp -r koala-memory ~/.hermes/plugins/koala-memory
Enable in Config
# ~/.hermes/config.yaml
plugins:
enabled:
- koala-memory
# ... other plugins
memory:
provider: koala # <-- Critical: only ONE external provider allowed
Restart Gateway
systemctl --user restart hermes-gateway
Agent Tools Available
After restart, agents get 3 tools:
| Tool | Description |
|---|---|
koala_recall | Search conversation memory by semantic similarity |
koala_write_fact | Manually write a fact to persistent memory |
koala_search | Alias for recall |
How it works:
on_turn_start→ captures user messageson_session_end→ extracts facts, embeds viaembed_text, stores viawrite_fact, upserts vectors viavector_upsert_fact- Background thread → non-blocking async processing
koala_recall("vector search config")→ returns relevant past conversations
🏗️ Build from Source
Prerequisites
- Rust 1.91+ (MSRV)
sqlite3dev headerspkg-config
Build
git clone https://github.com/dbillion/koala-rust
cd koala-rust
# Type-check only (fast)
cargo check
# Lint
cargo clippy
# Release build (~8-10 min first time)
cargo build --release
# Binary at target/release/koala-rust
Cross-Platform Builds (Local)
# Install cross
cargo install cross
# Linux x86_64
cross build --release --target x86_64-unknown-linux-gnu
# Linux ARM64
cross build --release --target aarch64-unknown-linux-gnu
# macOS x86_64
cargo build --release --target x86_64-apple-darwin # run on macOS
# macOS ARM64 (Apple Silicon)
cargo build --release --target aarch64-apple-darwin # run on macOS
# Windows x86_64 (run on Windows with MSVC build tools installed)
cargo build --release --target x86_64-pc-windows-msvc
GitHub Actions (Auto on Tag)
The repo includes two workflows in .github/workflows/:
| Workflow | Trigger | Purpose |
|---|---|---|
ci.yml | Push/PR to master | Format, clippy, type-check, test, cross-platform check (5 targets) |
release.yml | Tag push (v*) | Build 5 platform binaries + create GitHub Release |
Release on tag push:
git tag v0.3.0
git push origin v0.3.0
# → CI passes → release.yml builds all 5 targets → creates GitHub Release with binaries
Artifacts produced per release:
| Platform | Artifact Name |
|---|---|
| Linux x86_64 | koala-rust-x86_64-unknown-linux-gnu |
| Linux ARM64 | koala-rust-aarch64-unknown-linux-gnu |
| macOS x86_64 (Intel) | koala-rust-x86_64-apple-darwin |
| macOS ARM64 (Apple Silicon) | koala-rust-aarch64-apple-darwin |
| Windows x86_64 | koala-rust-x86_64-pc-windows-msvc.exe |
Each release includes SHA256SUMS.txt for verification.
📦 Plugin Development
WASM Plugin (Recommended)
Create a WAT file with required exports:
(module
(memory 1 10) ;; 10 pages = 640 KB
(export "memory" (memory 0))
;; Allocator for host→WASM data transfer
(func (export "allocate") (param $size i32) (result i32)
;; Return pointer to fresh memory
)
(func (export "deallocate") (param $ptr i32) (param $size i32)
;; Free memory
)
;; Manifest & tools (called by host after allocate+write)
(func (export "set_manifest") (param $ptr i32) (param $len i32))
(func (export "set_tools") (param $ptr i32) (param $len i32))
(func (export "get_manifest") (result i32))
(func (export "get_tools") (result i32))
;; Tool execution
(func (export "call_tool") (param $name_ptr i32) (param $name_len i32)
(param $input_ptr i32) (param $input_len i32)
(result i32))
)
Host calls: allocate() → writes JSON → set_manifest(ptr, len) / set_tools(ptr, len) → get_manifest() / get_tools() → call_tool().
See plugins/wasm/*.wat for examples: hash-tools, text-transform, json-tools.
Native Plugin
Shared library with C ABI:
// plugin.h
typedef struct { const char* name; const char* version; } PluginManifest;
typedef struct { const char* name; const char* description; const char* input_schema; } ToolDef;
PluginManifest* get_manifest();
ToolDef* get_tools(int* count);
char* call_tool(const char* tool_name, const char* input_json);
void free_string(char* s);
Compile: rustc --crate-type=cdylib plugin.rs -o libplugin.so
Install: koala-rust plugin-install --path ./libplugin.so --type native
🔒 Privacy & Security
- 100% local — no network calls except initial model download (~30 MB potion-base-8M from HuggingFace)
- Checked in the v0.3.3 source: HTTP is used only by the model download and the plugin marketplace (registry on GitHub). No telemetry code found. Offline build: #18.
- WASM sandbox — memory-limited, no host access
- A
max_memory_mbsetting exists but is not enforced anywhere in the code, and there are no fuel or time limits yet (#17).
- A
- Native plugins — only from trusted sources (you verify)
- Native plugins are shared libraries with full host access, outside the sandbox. Planned to be off by default (#17).
- SQLite — single file, easy to backup/encrypt
- koala-rust does not encrypt the file itself (#14). Use full-disk encryption for now.
- No telemetry — zero data leaves your machine
📊 Performance
| Operation | Latency (typical) |
|---|---|
| Fact write/read | < 1 ms |
| Embedding (256-dim) | ~50 ms (CPU) |
| Vector upsert | < 5 ms |
| Vector search (k=10) | < 10 ms |
| Sync merge (1000 ops) | ~100 ms |
| Plugin call (WASM) | ~1 ms overhead |
These are the author’s typical figures, not from a benchmark suite. Measured on the v0.3.3 Linux x86_64 binary: first embedding call about 1.1 s (model load), then write plus embed about 10 ms, recall on a small store 20 to 40 ms. Large-store benchmarks are still to do.
🗺️ Roadmap
| Version | Focus |
|---|---|
| v0.3 | Conversation auto-logging hook, better fact extraction (LLM-based) |
| v0.4 | Remote plugin registry, plugin signing/verification |
| v0.5 | Distributed sync (WebRTC/WebSocket), conflict resolution UI |
| v1.0 | Production hardening, benchmarks, migration tools |
v0.3.3 added the continuity tools (handoff, decisions, project status). Current, detailed work items live in the issues: #11 to #29.
🤝 Contributing
# 1. Fork & clone
# 2. Create branch
# 3. Make changes + tests
# 4. cargo check && cargo clippy && cargo test
# 5. PR with conventional commit: "feat: add X" / "fix: resolve Y"
📄 License
MIT — see LICENSE
🔗 Related
- Hermes Plugin:
koala-memory(in~/.hermes/plugins/koala-memory/) - koala-mcp Skill:
skills/koala-mcp/in this repo - MCP Spec: https://modelcontextprotocol.io
- sqlite-vec: https://github.com/asg017/sqlite-vec
- Model2Vec: https://github.com/MinishLab/model2vec-rs
- wasmtime: https://github.com/bytecodealliance/wasmtime