모자이크: 에이전트 메모리용 로컬 MCP 서버

Local MCP server for structured agent memory — hex lattice, hybrid retrieval, governed writes, and budgeted context — backed by HexxlaDB. 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. 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 theall-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// (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. 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. 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. 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. 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. 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. 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. 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. make ci # full pipeline (same as CI) make test # unit tests make integration # tagged integration tests Exploration and limits → TODOS.md · themes → docs/ROADMAP.md 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. MIT — see LICENSE.