scrinia

Persistent, portable memory for LLMs. Compresses text into NMP/2 artifacts, stores them locally, and exposes 2 MCP tools (guide and memory) so agents can remember, search, recall, and load reusable specialist skills across sessions. Built-in semantic search via Model2Vec (384-dim, ~22MB, zero native deps). Cross-process safe via OS-enforced file locks. Zero infrastructure required.

Benchmarks

How does a structured memory system compare to simpler approaches? We built a runnable benchmark suite that quantitatively compares three strategies:

• Scrinia — NMP/2 compressed artifacts, BM25+weighted field search, chunked retrieval
• Flat-file — all knowledge in one string (AGENTS.md-style), always fully loaded, substring search
• Auto memory — 200-line index always loaded, per-topic files loaded on demand (Claude-style)

Token efficiency (avg tokens per query)

Scaling (growth rate from 10 to 500 facts)

Cold start (tokens consumed before first query)

Search recall

All three systems achieve 100% recall on exact-term and natural-language queries. Scrinia's advantage is not accuracy — it's doing it at 1-5% of the token cost.

Cross-topic isolation

First query cost (cold start + query, 100 facts)

Where each system wins

Run the benchmarks yourself:

dotnet test tests/Scrinia.Tests --filter "FullyQualifiedName~Benchmarks"

Install

Build from source (.NET 10 SDK required):

git clone https://github.com/nickd-scrinia/scrinia
cd scrinia
dotnet build

# Publish trimmed single-file binary
.\publish.ps1 -OutputDir ./dist -Platform win-x64

# Download embedding model for semantic search (~22MB)
scri setup

# Optional: with Vulkan GPU-accelerated embeddings plugin
.\publish.ps1 -OutputDir ./dist -Platform win-x64 -WithVulkan

MCP setup

Add to your MCP client config (Claude Code, Cursor, Copilot, etc.):

{
  "mcpServers": {
    "scrinia": {
      "command": "scri",
      "args": ["serve"],
      "transport": "stdio"
    }
  }
}

For HTTP transport via the API server, see Server Administration.

CLI quick reference

Note: All mcp tools are availabl via cli, so they can be used in hooks, etc.

# Infrastructure
scri serve                                  # start MCP server (stdio); auto-downloads embedding model on first run
scri setup                                  # pre-download embedding model (rarely needed — serve auto-runs it)
scri config                                 # list/get/set workspace settings

# Cold-start / lifecycle
scri guide                                  # print the agent guide (run once per session)
scri restore                                # resume agent context (profile, patterns, session log)
scri reconcile                              # scan .scrinia/ for merge conflicts
scri consolidate --auto                     # deterministic housekeeping (hook-friendly, Tier 1)
scri consolidate --with-llm                 # add LLM pass: descriptions, summaries, fact extraction (Tier 2)
scri reindex                                # force rebuild of every vector file (rarely needed; auto-runs on model switch)

# Memory operations (grouped under "memory")
scri memory list                            # summary view (topics, keywords, stats)
scri memory list --summary=false            # full listing
scri memory search "auth"                   # hybrid BM25 + semantic search
scri memory store notes ./notes.md          # store a file as memory
scri memory store api:auth ./auth.md        # store under a topic
scri memory show api:auth                   # display memory content
scri memory forget api:auth                 # delete a memory
scri memory append notes ./more.md          # add a chunk
scri memory compact notes --keep-recent 3   # merge old chunks; keep 3 newest
scri memory link notes api:auth -r "see also" # bidirectional cross-reference

# Bundle files (grouped under "bundle")
scri bundle export api                      # export topic to .scrinia-bundle
scri bundle import ./bundle.scrinia-bundle  # import a bundle
scri bundle pack docs *.md                  # package raw files into a bundle

All commands accept --workspace-root to override the workspace directory and --json for machine-parseable JSON output. The one-shot scri migrate (v1→v2 store layout) is still callable but hidden from --help.

Memory naming

MCP tools

2 tools available via scri serve.

Built-in skills

Eight skills ship with scrinia and load via memory('recall', { path: '/skill/{name}' }):

Projects can override any built-in by writing to /skill/{name} — the on-disk version takes precedence and is reusable across sessions.

Plans, retrospectives, agent norms, and findings are all just memories — searchable via memory('search'), organized via reserved paths (/findings/, /learn/, /agent/, /patterns/, /sessions/). No separate database, no separate tools.

Documentation

User Guides

• Getting Started — overview, installation, quick start
• CLI Reference — commands, configuration, embedding providers, MCP client setup
• Server Administration — deployment, authentication, REST API, web UI, Docker
• Web UI — React SPA component architecture, dev setup, deployment
• Troubleshooting — common issues, plugin failures, recovery

Architecture

• Overview — system design, project structure, dependency graph
• CLI Architecture — workspace discovery, plugin host, MCP tools
• Server Architecture — startup, middleware, auth, multi-store, plugins
• Core Internals — IMemoryStore, NMP/2 encoding, search algorithms
• Embeddings Architecture — providers, vector store, HNSW, hybrid scoring

Specification

• NMP/2 Spec — encoding format specification

Running tests

dotnet test tests/Scrinia.Tests                   # 716 CLI + MCP + storage + embeddings + reindex tests
dotnet test tests/Scrinia.Server.Tests            # 63 server tests
dotnet test tests/Scrinia.Merge.Tests             # 18 merge-conflict tests
dotnet test tests/Scrinia.Plugin.Embeddings.Tests # 12 Vulkan embeddings plugin tests
dotnet test tests/Scrinia.Plugin.Llm.Tests        # 15 Vulkan LLM plugin tests

Running benchmarks

BenchmarkDotNet is used for measuring hot-path performance (BM25 corpus stats, HNSW search). Run from the repo root:

# Run everything (a full pass takes several minutes)
dotnet run -c Release --project tests/Scrinia.Benchmarks

# Run a subset and emit a machine-readable JSON summary
dotnet run -c Release --project tests/Scrinia.Benchmarks -- \
    --filter "*Bm25*" --exporters json

JSON exports land in tests/Scrinia.Benchmarks/BenchmarkDotNet.Artifacts/ and can be diffed against a committed baseline to gate regressions in CI.

License

BSD-3-Clause. Copyright (c) 2026 Nick Daniels.