Mosaic

Local MCP server for structured agent memory — hex lattice, hybrid retrieval, governed writes, and budgeted context — backed by HexxlaDB.

Why Mosaic

Mosaic keeps agent memory on infrastructure you operate: MCP on localhost, optional encryption at rest, and code you can inspect and extend. Retention guidance and delete permission follow policy you define, so context is not outsourced by default.

Agents fail in production when recalled facts drift or sessions read as unrelated reruns. Mosaic gives memory that accumulates cleanly across sessions, so the assistant can anchor on durable state instead of re-deriving intent from prompts alone.

It is backed by HexxlaDB: a hex lattice lays out related cells for spatial, bounded expansion from a seed; hybrid retrieval combines similarity with structured constraints; callers can record conflicting updates as explicit seams rather than losing the disagreement in embedding space. Operators describe behaviour in YAML; callers receive budgeted context within explicit limits you can trace and revise.

Get started

What Mosaic needs

• Ollama only for operations that turn text into vectors, including semantic search, text embedding writes, and mosaic-seed. Database creation, health, lexical/structured reads, raw-vector writes, and the other non-embedding tools do not require it. The sample configs/config.yaml expects Ollama on http://127.0.0.1:11434 with the all-minilm model; adjust it or see MOSAIC_CONFIG.md.

Step 1 — Clone the repo

git clone https://github.com/hexxla/mosaic.git
cd mosaic

Step 2 — Build

You need Go 1.27+ and Task 3. From the repo root:

go mod download
task build-mosaic-mcp build-mosaic-create-db

After the build tasks run, your programs are under bin/<platform>/ (the command prints the paths). Later steps assume bin/linux-amd64/ — use the folder Task created on your machine (add .exe on Windows).

Developers: task seed / task reseed; task build-mosaic-seed builds a mosaic-seed binary.

Step 3 — Create a database

Pick a path for the DB file (-db). Use the same -db value (or MOSAIC_DB_PATH) again when you start mosaic-mcp (Step 5).

./bin/linux-amd64/mosaic-create-db -db ./data/mosaic.db

Encrypted databases: If you pass -db-passphrase or MOSAIC_DB_PASSPHRASE to mosaic-create-db, the new database is encrypted on disk. Omit both for an unencrypted file. Full behavior: DATABASE_CREATION.md (MOSAIC_DB_PASSPHRASE is usually safer than -db-passphrase where ps lists process arguments).

./bin/linux-amd64/mosaic-create-db -db ./data/mosaic.db -db-passphrase 'use-a-strong-secret'

Step 4 — Policy file (YAML)

An example version: 1 policy ships at configs/config.yaml — copy or edit from there for mosaic-mcp ( -policy or MOSAIC_POLICY_FILE). All keys → MOSAIC_CONFIG.md.

Step 5 — Run the MCP server

./bin/linux-amd64/mosaic-mcp -policy configs/config.yaml -db ./data/mosaic.db

Step 6 — Point your MCP client at the URL

By default Mosaic serves Streamable HTTP at http://127.0.0.1:8787/mcp. Tune MOSAIC_MCP_ADDR / MOSAIC_MCP_PATH if needed (Taskfile).

Configure your MCP client through its UI or configuration file. A typical mcpServers entry is:

{
  "mcpServers": {
    "mosaic": {
      "url": "http://127.0.0.1:8787/mcp"
    }
  }
}

Client configuration locations and schemas vary; use the documentation for your MCP host.

How Mosaic works

Mosaic fronts HexxlaDB — a single embedded engine with B+tree pages for structure, optional HNSW for embeddings, MVCC for truthful versions, and sensible handling of large payloads. You do not assemble that yourself; you expose it through one MCP surface your agent can learn once.

Lattice memory, not a flat pile

Memories sit on hex coordinates; related items can be near in the same way they are near on disk. Expansion from a seed is spatial and bounded — you pull context in rings with intent, not by hoping the top similarity hits cohere. The benefit: reproducible, explainable neighbourhoods instead of a black-box vector grab bag.

Cell writes make placement explicit. mosaic_hexxla_put_cell defaults to an exact coordinate and refuses to replace a live cell unless allow_overwrite is set. With placement: near_anchor, (q,r) is a caller-chosen semantic anchor and Mosaic atomically selects the first free coordinate in deterministic ring order within a bounded radius. The response returns the actual coordinate; Mosaic does not infer semantic meaning or silently relocate existing cells.

Retrieval that stacks

Semantic similarity, structured filters, and lexical search coexist. You find candidates with the signal that fits the question, then assemble a context pack under a UTF-8 byte budget (optionally estimated from a token target) so the model sees a curated slice of the lattice. Mosaic stays provider-neutral; exact tokenizer accounting belongs with the client that renders the final model request.

Contradictions you can keep

When two memories disagree, callers can record a conflict seam with mosaic_hexxla_mark_conflict; an intentional replacement uses mosaic_hexxla_mark_supersedes. Neither Mosaic nor HexxlaDB infers semantic disagreement automatically. These visible relationships let the model reason about conflict instead of silently letting a newer embedding win.

Policy your operators can sign

YAML describes capture guidance, whether deletes are permitted, embedding settings, housekeeping after deletes, and encryption hints—not scattered conventions in prose prompts. Delete permission and configured maintenance are enforced by the server; capture modes and notes guide clients but do not auto-save turns.

Telemetry without theatre

Insight into footprint, versioning, integrity — grounded in MVCC-aware checks — sits alongside optional automatic prune and compact after deletes so conscientious workloads do not choke on dormant history unless you intend that trade-off.

For command names, YAML keys, and troubleshooting, begin with docs/mosaic/ and the local docs/architecture/. HexxlaDB’s storage/API docs live in the upstream docs/hexxladb tree. AGENTS.md and CHANGELOG.md cover contribution layout and shipped changes.

Ratchet: Tool flow governance

Mosaic can optionally use mcp-ratchet to enforce configured tool prerequisites within each real MCP session. Ratchet is disabled when no configuration path is supplied:

mosaic-mcp -db ./data/mosaic.hexxla -ratchet-config configs/ratchet.yaml
# or: MOSAIC_RATCHET_CONFIG_FILE=configs/ratchet.yaml mosaic-mcp -db ./data/mosaic.hexxla

The supplied policy requires a fresh successful mosaic_hexxla_list_tags call before each mosaic_hexxla_put_cell. Context loads and deletes require one recent successful retrieval call. Tools absent from the policy remain unrestricted; repeated rules for a tool are alternatives (OR). State is process-local and resets on restart. Mosaic does not expose Ratchet tokens, sessions, event APIs, or additional observability endpoints.

The gate controls call ordering, not client authentication or authorization. See configs/ratchet.yaml and docs/mosaic/RATCHET_INTEGRATION.md for the exact contract and limitations.

Reliable tool use from agents

MCP does not force models to call tools. Reinforce behavior with AGENTS.md, retention.notes in your policy YAML (they are injected into server instructions), and docs/mosaic/DEVELOPMENT_TOOLING.md. The steady pattern is discover candidates, assemble a budgeted context pack, and persist only where policy permits. Runtime tools/list schemas are the authoritative payload contract.

Development

task ci          # full pipeline (same as CI)
task test        # unit tests
task integration # tagged integration tests

Roadmap

Exploration and limits → TODOS.md · themes → docs/ROADMAP.md

Sponsorship

Mosaic is open source and under active development. If it's useful to your work — or you want to accelerate the roadmap (distributed replication, materialized views, richer seam semantics) — sponsorship is the most direct way to help.

• GitHub Sponsors: github.com/sponsors/hexxla
• Monero (XMR): 46shAhAihZ3dmVHGU4V6H2ZZt21ex8xydB7Awkxaheq4U1VZFoK53K92tsqhnL8roV2bV8pQWCryR3yNRJJd5gAeBsZUXPF
• Open Collective: coming soon

Sponsors get early access to roadmap discussions, priority issue triage, and attribution in release notes.

License

MIT — see LICENSE.