Zakira.Exchange 0.1.0

Zakira.Exchange

An MCP server and CLI tool that enables AI agents to save, share, and search memories. Built with .NET 10, standalone with no external service dependencies.

Memories are stored in SQLite with full-text search (FTS5) and semantic vector search (ONNX embeddings), merged via Reciprocal Rank Fusion for hybrid retrieval.

Documentation

Features

• Structured memory entries with category, key, data, and rich metadata (author, reason, tags, custom key-value pairs, auto-managed timestamps)
• Categories/tables to separate different types of memories
• Full CRUD - create, edit, delete, get, list entries
• Hybrid search (RAG) - BM25 keyword search + cosine vector similarity via all-MiniLM-L6-v2 ONNX embeddings, fused with Reciprocal Rank Fusion (k=60)
• Access mode control - restrict which operations agents can perform
• Const-category mode - lock all operations to a single category via --category, hiding the parameter from agents
• Single tool, two modes - use zakira as a CLI tool, or zakira mcp to start as an MCP server
• Concurrent access - multiple processes can access the same database simultaneously via SQLite WAL mode
• Lazy ONNX model loading - the model is only loaded when create, edit, or search operations are invoked
• Environment variable configuration - all CLI flags have corresponding environment variables

Quick Start

Prerequisites

• .NET 10 SDK

1. Download the ONNX model

# PowerShell
./scripts/download-model.ps1

# Bash
./scripts/download-model.sh

This downloads all-MiniLM-L6-v2.onnx (~90MB) and vocab.txt (~230KB) from HuggingFace into src/Zakira.Exchange.Core/Models/.

2. Build

dotnet build Zakira.Exchange.slnx

3. Use as a CLI tool

dotnet run --project src/Zakira.Exchange.Cli -- create general my-key --data "Hello, world!"
dotnet run --project src/Zakira.Exchange.Cli -- list
dotnet run --project src/Zakira.Exchange.Cli -- search "greeting"
dotnet run --project src/Zakira.Exchange.Cli -- categories

4. Start as an MCP server

dotnet run --project src/Zakira.Exchange.Cli -- mcp
dotnet run --project src/Zakira.Exchange.Cli -- mcp --access-mode read-only
dotnet run --project src/Zakira.Exchange.Cli -- mcp --category notes --db ./notes.db

MCP Server Configuration

Add to your MCP client configuration (e.g. Claude Desktop, VS Code, Cursor):

{
  "servers": {
    "zakira": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["run", "--project", "path/to/src/Zakira.Exchange.Cli", "--", "mcp"]
    }
  }
}

Or if installed as a dotnet tool:

{
  "servers": {
    "zakira": {
      "type": "stdio",
      "command": "zakira",
      "args": ["mcp", "--database-path", "./memories.db"]
    }
  }
}

See the MCP Server documentation for more configuration examples.

MCP Tools

The server exposes up to 6 tools depending on the access mode:

Tools not permitted by the access mode are simply not registered, making them invisible to agents.

CLI Commands

zakira create <category> <key> --data <text> [--author <name>] [--reason <text>] [--tags <csv>] [--custom <json>]
zakira edit <category> <key> [--data <text>] [--author <name>] [--reason <text>] [--tags <csv>] [--custom <json>]
zakira delete <category> <key>
zakira get <category> <key>
zakira list [--cat <name>] [--top <n>] [--author <name>] [--tags <csv>] [--before <iso8601>] [--after <iso8601>]
zakira search <query> [--cat <name>] [--top <n>] [--author <name>] [--tags <csv>]
zakira categories
zakira mcp                              # Start as MCP server

See the CLI Reference for detailed command documentation.

Concurrent Access

Multiple processes can access the same database simultaneously. SQLite WAL mode is enabled by default, so:

• An MCP server can be running while you query the same database via CLI
• Multiple MCP server instances can share the same database
• Readers are never blocked by writers

# Terminal 1: MCP server running, agent is using it
zakira mcp --db ./memories.db

# Terminal 2: Query the same database via CLI
zakira list --db ./memories.db
zakira search "something" --db ./memories.db

Options

CLI flags

All flags are global and apply to every subcommand, including mcp.

Environment variables

Access modes

See the Configuration documentation for more details.

Architecture

Zakira.Exchange.Core        Business logic, storage, search, embeddings
Zakira.Exchange.Cli         Single entry point: CLI commands + MCP server (via 'mcp' subcommand)

How search works

1. Keyword search: SQLite FTS5 with BM25 scoring against the entry's category, key, data, author, reason, and tags
2. Vector search: ONNX all-MiniLM-L6-v2 generates 384-dim embeddings; cosine similarity via dot product (L2-normalized vectors)
3. Fusion: Reciprocal Rank Fusion (k=60) merges both ranked lists into a single result set
4. Post-filtering: Author and tag filters are applied after fusion

Each entry is embedded as a single unit (key, data, tags, and reason joined with |). No chunking is needed since memories are typically short structured entries.

See the Architecture documentation for a deep dive into internals.

Documentation

Full documentation is available at moaidhathot.github.io/Zakira.Exchange:

• Getting Started - Prerequisites, download, build, and first use
• CLI Reference - Complete command-line interface documentation
• MCP Server - Setting up Zakira as an MCP server for AI agents
• Configuration - CLI flags, environment variables, and access modes
• Architecture - Internals, search algorithm, and project structure

License

Unlicense - public domain.