Memoria

Personal wiki store with a Rust HTTP server (REST + static UI + MCP streamable HTTP) and a React front end. Vault layout follows the LLM Wiki idea: immutable raw/, compiled wiki/, YAML config, optional SQLite-derived index.

Roadmap and step-by-step execution: see ROADMAP.md. Default development is native: cargo and npm on your machine (Phase 0 there). Do not use Docker for the day-to-day loop—image builds are slow and unnecessary until you want a deployment-like run or a stable release artifact.

Prerequisites

• Rust 1.88+ (see rust-toolchain.toml if present)
• Node.js 20+ and npm (for the web UI)

Development (recommended)

cp memoria.example.yaml memoria.yaml
# Build UI
(cd web && npm install && npm run build)
# Run API + serve web/dist
cargo run -p memoria-server -- --config memoria.yaml

Vite dev server (npm run dev in web/): run it from the web directory so the config’s project root is correct. If the browser shows disallowed MIME type or empty type for /node_modules/.vite/deps/..., stop the server, run rm -rf web/node_modules/.vite, then npm run dev again. Also try disabling ad-blockers on localhost (some block URLs containing node_modules).

• Health: http://127.0.0.1:8787/health
• Version: http://127.0.0.1:8787/api/v1/version
• UI: http://127.0.0.1:8787/ (if server.static_dir points at web/dist)

Maintenance hook (optional maintenance_token in config):

curl -X POST http://127.0.0.1:8787/hooks/maintenance \
  -H "Authorization: Bearer YOUR_TOKEN"

MCP (Cursor and other clients)

The server exposes streamable HTTP MCP at http://<host>:<port> + mcp.path (default /mcp). For Cursor, add the memoria server to your user MCP config at ~/.cursor/mcp.json (e.g. "url": "http://127.0.0.1:8787/mcp"), then restart Cursor. Use the same URL when Memoria runs in Docker with port 8787 published.

If maintenance_token is set, add Authorization: Bearer <token> under headers for that server in ~/.cursor/mcp.json (or use config interpolation).

Example tool: memoria_info returns server version and configured vault/store paths.

HTTP API (selected)

Method	Path	Purpose
GET	/api/v1/wiki/pages	Indexed wiki pages (SQLite)
GET	/api/v1/wiki/search?q=…	Search indexed path and title (case-insensitive substring)
GET	/api/v1/wiki/page?path=…	Raw markdown from the wiki vault
GET	/api/v1/wiki/graph	nodes + directed edges from [[wikilinks]] (run maintenance after edits)
GET	/api/v1/admin/mcp-events/daily?days=14	Daily MCP tool call counts (requires Authorization: Bearer if maintenance_token is set)
POST	/hooks/maintenance	Reindex *.md into SQLite + optional git pull

After changing markdown on disk, run maintenance so the wiki list and graph update.

Docker (optional — deployment / smoke test)

Use this when you need a containerized run or to validate docker compose before release—not for iterative development.

Requires Docker with Compose v2.

cd Memoria
docker compose up --build -d

Then open http://localhost:8787/ — UI, API, and MCP are on port 8787. Data lives in ./data on your machine (raw/, wiki/, memoria.db).

• Health: http://localhost:8787/health
• MCP (e.g. Cursor on your host): http://127.0.0.1:8787/mcp — same URL as a local server; ensure this matches ~/.cursor/mcp.json.

Stop: docker compose down. Logs: docker logs -f memoria.

To use your own config, copy memoria.docker.yaml, edit, and add a bind mount in docker-compose.yml for /config/memoria.yaml.

Example wiki (reader + graph)

Committed sample pages live in examples/sample-wiki/. Copy into your local vault (gitignored):

./scripts/seed-example-wiki.sh

Then start the server and use Admin → Run reindex now, or curl -X POST http://127.0.0.1:8787/hooks/maintenance (with Authorization: Bearer … if maintenance_token is set). See examples/README.md.

Layout

• crates/memoria-core — config types and storage traits
• crates/memoria-store — SQLite derived index + local vault
• crates/memoria-server — Axum binary
• web/ — Vite + React
• ui_examples/ — UI reference screenshots (not shipped in the binary)

License

MIT OR Apache-2.0 (see workspace Cargo.toml).