---

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 and access 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; conflicting updates surface as seams rather than disappearing into the 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 running on your machine. Mosaic needs it for embeddings (semantic search and anything else that turns text into vectors). The sample configs/config.yaml expects Ollama on http://127.0.0.1:11434 with the all-minilm model; adjust in that file or see MOSAIC_CONFIG.md for env vars and options.

---

Step 1 — Clone the repo

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

---

Step 2 — Build

You need Go 1.26+. From the repo root:

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

After make, your programs are under bin/<platform>/ (the command prints the paths). Later steps assume bin/linux-amd64/ — use whatever folder make created on your machine (add .exe on Windows). There are no downloadable release binaries yet.

Developers: make seed / make reseed; make 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 (Makefile).

Cursor: add a mcpServers entry (often .cursor/mcp.json next to your project):

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

Other clients ship different config files or UIs — use their MCP documentation rather than copying this verbatim.

---

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.

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 byte or token budget so the model sees a curated slice of the lattice — not a blunt truncation that happens to fit the window.

Contradictions you can keep

When two memories disagree, HexxlaDB records seams — visible relationships the model can reason about — instead of silently letting the newer embedding win. Supersession tracks how preferences evolve without pretending history never happened. The benefit: auditability and honest dialogue when knowledge conflicts.

Policy your operators can sign

YAML describes what to retain, whether deletes are permitted, embeddings settings, housekeeping after deletes, encryption hints — not scattered conventions in prose prompts. Agents still improvise reasoning; persistence becomes enforceable.

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, explore the docs/ tree — begin with docs/mosaic/, then docs/hexxladb/ or docs/architecture/ as needed. AGENTS.md and CHANGELOG.md cover contribution layout and shipped changes.

---

Ratchet: Tool flow governance

Mosaic integrates mcp-ratchet to enforce tool call sequences and prerequisites. This prevents agents from making unsafe or context-free mutations by requiring specific discovery or validation steps before write operations.

Features

• Prerequisite validation: Tools can require other tools to be called first (e.g., put_cell requires list_tags to prevent tag fragmentation)
• One-time use tokens: Prerequisite tokens can be consumed after use, forcing fresh discovery for each operation
• Time-bound sessions: Tokens expire after a configurable duration, ensuring context remains current
• Flexible rules: Multiple prerequisite rules per tool (e.g., put_cell accepts list_tags, tag_counts, or retrieval tools)
• Session management: Session-based token tracking across tool calls
• Observability: Real-time event capture, WebSocket streaming, and HTTP endpoints for monitoring tool usage, session state, and token issuance

Benefits

• Tag hygiene: Forces agents to review available tags before writing, preventing fragmentation
• Context awareness: Requires retrieval tools before mutations to verify cell existence and understand context
• Budget enforcement: Requires budget estimation before large context loads
• Auditability: Tool call sequences are logged and validated against policy
• Safety: Prevents blind writes by requiring discovery steps

Configuration

Ratchet rules are defined in configs/ratchet.yaml. Each rule specifies:

• tool: The tool being governed
• prerequisite: Required prerequisite tool (empty string means no prerequisite)
• error_message: Custom error message shown when validation fails
• one_time_use: Whether the prerequisite token is consumed after use
• expiry: Time limit for token validity (ignored when one_time_use: true)

Example rule:

- tool: "mosaic_hexxla_put_cell"
  prerequisite: "mosaic_hexxla_list_tags"
  error_message: "Before saving a cell, review available tags to prevent fragmentation. Call mosaic_hexxla_list_tags to see current vocabulary."
  one_time_use: true

Observability

Ratchet observability is configured in the same file under the observability section:

observability:
  enabled: true
  storage_type: memory # memory or hexxladb
  retention_days: 0 # 0 = keep all events

When enabled, Mosaic exposes HTTP endpoints for monitoring:

• GET /observability/stats - Aggregate statistics (total events, tokens issued, active sessions)
• GET /observability/events?session_id=<id>&limit=<n> - Paginated event history
• WS /observability/stream - WebSocket endpoint for real-time event streaming

For detailed configuration options and examples, see docs/mosaic/RATCHET_INTEGRATION.md.

---

Reliable tool use from agents

MCP does not force models to call tools. Reinforce behavior with project rules, retention.notes in your policy YAML (they are injected into server instructions), and .cursor/rules/mosaic-mcp-agent.mdc or docs/mosaic/AGENT_CLIENT_WORKFLOWS.md. The steady pattern is discover candidates, assemble a budgeted context pack, and persist only where policy permits — docs/mosaic/ spells out names and payloads.

---

Development

make ci          # full pipeline (same as CI)
make test        # unit tests
make 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.