Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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

ItemMeasured
Binary14.9 MB (macOS arm64), 16.3 MB (Windows), 21.5 MB (Linux arm64), 24.4 MB (Linux x86_64)
Memory, server idle18 MB
Memory, after embedding model is loaded52 MB
Embedding model (one-time download from Hugging Face)about 30 MB (potion-base-8M, 256 dimensions)
Database with 3 facts and vector tablesabout 1.2 MB (184 KB without vector tables)
Write plus embed, after model loadabout 10 ms
Semantic recall on a 3-fact storeabout 20 to 40 ms
Needs network after the model is cachedNo. 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-rustMem0LettaZep / GraphitiCogneeDakera
ShapeSingle binary, SQLiteLibrary plus cloudFull agent runtimeTemporal knowledge graphGraph pipelineSingle Rust binary
LicenseMITApache 2.0Apache 2.0Graphiti Apache 2.0, Zep cloud closedApache 2.0MIT open-core
Offline / air-gappedYes, once model cachedLimited, needs local LLM setupYesLibrary only, needs graph DBYesYes
Extra services to runNoneVector DB for self-hostPostgres or SQLiteNeo4j, FalkorDB or NeptuneOptional graph/vector DBsNone
Write pathLocal embedding onlyLLM extraction per addLLM tool callsGraph extractionMulti-stage LLM pipelineLocal embedding
Footprint15 to 24 MB binary, 18 to 52 MB RAMNot statedNot statedNot statedNot statedabout 101 MB binary
Encryption at restNoNot statedNot statedCloudYes (stated)AES-256-GCM (stated)
Compliance claimsNoneSOC 2 Type I, “HIPAA ready”Enterprise SSOSOC 2 Type II, HIPAA BAA (cloud)GDPR-orientedNot stated
List price (managed)Free$19 to $249 / month$20 / month and usage$125 to $375 / monthusage basedNo 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 planPer monthPer 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

CapabilityStatusTracking
Runs fully on your own machine, no cloudWorks (model cached once)#18 for first-run download
Semantic recall, version historyWorks
Verified deletion of a fact and all its versionsBroken, old versions and bytes stay#11
Retention rules (TTL)Missing#12
“What did the agent know on date X”Missing#13
Encryption at restMissing#14
Tamper-evident audit logMissing#15
Who can read what (labels, namespaces)Missing#16
Signed and sandboxed pluginsPartial. The built-in hash-tools demo fails#17, #29
HIPAA, SOC 2, FedRAMP, CMMCNone. 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

AreaIssues
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

FeatureDescription
Persistent FactsVersioned key-value storage with SQLite
Semantic SearchExact KNN vector search via sqlite-vec (256-dim embeddings)
Real EmbeddingsLocal Model2Vec + potion-base-8M (256-dim, ~30 MB, downloads from Hugging Face once on first use)
Knowledge GraphEntities, observations, relations with graph traversal
Task ManagementStructured tasks/notes with queries and updates
CRDT SyncVector clocks + last-write-wins for multi-agent collaboration
WASM PluginsSandboxed plugins (wasmtime) + native plugins (libloading)
Plugin MarketplaceInstall plugins. SHA256 checksum is checked when the registry lists one. No signatures yet (#17)
MCP Server60 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.

PlatformRelease archive
Linux x86_64koala-rust-x86_64-unknown-linux-gnu.tar.gz
Linux ARM64koala-rust-aarch64-unknown-linux-gnu.tar.gz
macOS Intelkoala-rust-x86_64-apple-darwin.tar.gz
macOS Apple Siliconkoala-rust-aarch64-apple-darwin.tar.gz
Windows x86_64koala-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 CaseValue
1Institutional Knowledge RetentionNever lose technical decisions, debugging context, or tribal knowledge when team members leave. Semantic search finds “why we chose X” instantly.
2Multi-Agent CollaborationResearch, coding, and review agents share a synchronized fact base via CRDT — no conflicting states, no manual handoffs.
3Compliance & Audit TrailVersioned facts + timestamps = immutable record of decisions. Export for SOC2, GDPR, or internal audits.
4Cross-Session ContinuityAgents resume exactly where they left off — context, tasks, learned patterns persist across restarts, days, machines.
5Private AI Memory (Air-Gapped)100% local, no API keys, no cloud. Runs in secure environments, regulated industries, offline deployments.
6Plugin-Driven Workflow AutomationInstall WASM plugins for custom transformers (hash, JSON, text, domain-specific). Extend without recompiling.
7Semantic Search over Conversations“What did we decide about auth last month?” → vector search returns relevant turns, not keyword matches.
8Knowledge Graph for Domain ModelingEntities + observations + relations = queryable domain model. “Show all services depending on PostgreSQL.”
9Task Handoff Between AgentsStructured tasks with state, priority, assignee. Agent A creates, Agent B picks up, Agent C reviews — all tracked.
10Embedding-Powered RAG Without CloudLocal 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-delete leaves 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 --help of v0.3.3. Semantic recall (recall, remember_semantic) is MCP-only for now (#22).


🔌 MCP Tools (60 Total)

CategoryTools
Healthhealth
Factswrite_fact, read_fact, list_facts, read_fact_versions, delete_fact, delete_fact_prefix
Entitiescreate_entities, add_observations, open_nodes, search_nodes, create_relations
Taskscreate_task_or_note, query_tasks, update_task
Neural Modelmodel_init, model_train, model_predict, model_status, feedback, explain_rank, sequential_thinking, conclusion, thought_history, thought_reset, model_save, model_load
Vector Searchvector_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 memoryremember_semantic, recall, reindex_facts
Continuitybootstrap_context, create_handoff, get_project_context, get_user_context, record_decision, search_memory, update_project_status
Embeddingsembed_text, embed_batch
Pluginsplugin_load, plugin_call, plugin_list, plugin_discover
Marketplaceplugin_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

CapabilityDescription
Tool ReferenceAll 50 MCP tools with parameters, examples, error handling
Workflow PatternsCommon patterns: fact extraction → embed → upsert → search
Best PracticesWhen to use facts vs entities vs tasks, naming conventions
Integration RecipesClaude Desktop, Hermes, custom MCP clients
TroubleshootingCommon 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:

ToolDescription
koala_recallSearch conversation memory by semantic similarity
koala_write_factManually write a fact to persistent memory
koala_searchAlias for recall

How it works:

  1. on_turn_start → captures user messages
  2. on_session_end → extracts facts, embeds via embed_text, stores via write_fact, upserts vectors via vector_upsert_fact
  3. Background thread → non-blocking async processing
  4. koala_recall("vector search config") → returns relevant past conversations

🏗️ Build from Source

Prerequisites

  • Rust 1.91+ (MSRV)
  • sqlite3 dev headers
  • pkg-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/:

WorkflowTriggerPurpose
ci.ymlPush/PR to masterFormat, clippy, type-check, test, cross-platform check (5 targets)
release.ymlTag 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:

PlatformArtifact Name
Linux x86_64koala-rust-x86_64-unknown-linux-gnu
Linux ARM64koala-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_64koala-rust-x86_64-pc-windows-msvc.exe

Each release includes SHA256SUMS.txt for verification.


📦 Plugin Development

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_mb setting exists but is not enforced anywhere in the code, and there are no fuel or time limits yet (#17).
  • 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

OperationLatency (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

VersionFocus
v0.3Conversation auto-logging hook, better fact extraction (LLM-based)
v0.4Remote plugin registry, plugin signing/verification
v0.5Distributed sync (WebRTC/WebSocket), conflict resolution UI
v1.0Production 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


  • 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

Quick Start

Installation

cargo install --git https://github.com/dbillion/koala-rust

Starting the MCP Server

export KOALA_STATE_DIR=~/.koala
koala-rust --serve

CLI Commands

# Write and read facts
koala-rust fact-write "project_name" "Koala"
koala-rust fact-read "project_name"

# Health check
koala-rust health

Architecture

See the Full Architecture Documentation for technical diagrams and subsystem breakdown.

API Reference

The full Rust crate documentation is available at API Reference.