understory 🌱

understory 🌱

Memory that grows.

The layer beneath your agents: a self-wiring, plain-markdown memory. Every fact your agents learn is filed as a markdown concept, cross-linked into a living knowledge graph, and kept healthy by the agent itself — searchable, diffable, and entirely yours. Runs great on local models.

Bundles follow the Open Knowledge Format (OKF) v0.1 spec — plain markdown files with YAML frontmatter, readable by humans, diffable in git, portable across tools.

Three ways in, one agent:

• MCP server — memory_query / memory_add / memory_update / memory_status / memory_maintain tools over stdio or streamable HTTP. Each call drives an internal LLM agent with the OKF spec in its system prompt.

• Web UI — browse the bundle (tree, concept viewer with Mermaid diagrams, update log, conformance badge), see the memory as an Obsidian-style force-directed graph (drag/pan/zoom, colored by type, sized by connections, orphans ringed red, click to open), and chat with the same agent to test it. Tool calls render inline so you can watch it work.

• Query-path replay — every agent run (query/mutation/chat) records its traversal (searches → reads → writes) as a compact notation, persisted under <bundle>/.traces/. The graph view lists recent runs; selecting one replays the path as numbered directed hops over the graph — visited concepts ringed, search hits dotted, everything else faded.

• CLI — pnpm agent:query "..." / pnpm agent:mutate "..." smoke entries.

• Profiles — optionally host several isolated memories on one server, each selected by its own API key. See Profiles.

Design rule: conformance is enforced in code, not prompts. The deterministic bundle layer validates frontmatter (type required), regenerates index.md files, appends log.md entries (newest-first, spec §7), and sandboxes all paths to the bundle root. The LLM decides what to change; the code guarantees the result is a conformant bundle.

Quick start (Docker)

No clone needed — the image is public. Save this as docker-compose.yml:

services:
  understory:
    image: ghcr.io/thecodacus/understory:latest
    ports:
      - "3800:3800"
    # Lets the container reach a llama.cpp server running on the host via
    # http://host.docker.internal:8080/v1 (see "Local llama.cpp" below).
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      # Your memory lives here as plain markdown — a named volume, or point
      # a bind mount (e.g. ./my-memory:/bundle) at any OKF bundle.
      - understory-memory:/bundle
    environment:
      BUNDLE_ROOT: /bundle
      LLM_API_BASE_URL: ${LLM_API_BASE_URL}
      LLM_API_KEY: ${LLM_API_KEY}
      LLM_API_FORMAT: openai
      LLM_MODEL: ${LLM_MODEL:-}
      # Optional fallback
      LLM_FALLBACK_API_BASE_URL: ${LLM_FALLBACK_API_BASE_URL:-}
      LLM_FALLBACK_API_KEY: ${LLM_FALLBACK_API_KEY:-}
      LLM_FALLBACK_API_FORMAT: ${LLM_FALLBACK_API_FORMAT:-openai}
      LLM_FALLBACK_MODEL: ${LLM_FALLBACK_MODEL:-}
    restart: unless-stopped

volumes:
  understory-memory:

docker compose up -d

Choosing a provider

The generic provider system supports any OpenAI-compatible or Anthropic-compatible API. Set LLM_API_BASE_URL + LLM_API_KEY + LLM_MODEL and leave LLM_PROVIDER unset.

DeepSeek:

LLM_API_BASE_URL=https://api.deepseek.com/v1 LLM_API_KEY=sk-... LLM_MODEL=deepseek-chat

OpenAI:

LLM_API_BASE_URL=https://api.openai.com/v1 LLM_API_KEY=sk-... LLM_MODEL=gpt-4o

Anthropic (Claude):

LLM_API_BASE_URL=https://api.anthropic.com/v1 LLM_API_KEY=sk-ant-... LLM_API_FORMAT=anthropic LLM_MODEL=claude-sonnet-5

Groq:

LLM_API_BASE_URL=https://api.groq.com/openai/v1 LLM_API_KEY=gsk_... LLM_MODEL=llama-3.3-70b-versatile

Local llama.cpp:

LLM_API_BASE_URL=http://host.docker.internal:8080/v1 LLM_MODEL=

When understory runs in Docker, localhost is the container itself, not the host — so a llama-server on the host is reached at host.docker.internal (the compose files above already map it via extra_hosts). Running from source on the same box as llama-server, use http://localhost:8080/v1.

Local llama.cpp with DeepSeek fallback:

LLM_API_BASE_URL=http://host.docker.internal:8080/v1 LLM_MODEL= \
LLM_FALLBACK_API_BASE_URL=https://api.deepseek.com/v1 LLM_FALLBACK_API_KEY=sk-... LLM_FALLBACK_MODEL=deepseek-chat

The old LLM_PROVIDER + per-provider key env vars still work (backward-compatible) but are deprecated.

Then:

• Web UI → http://localhost:3800 — browse the memory, watch the graph, chat with the agent

• MCP endpoint → http://localhost:3800/mcp (streamable HTTP) — register it in any MCP client:

  Copy

  claude mcp add --transport http ustory http://localhost:3800/mcp

• Your agent now has memory_query / memory_add / memory_update / memory_status / memory_maintain, and gets a seed overview of the memory at every session start.

Teach it something (memory_add: "We deploy on Fridays, never Mondays"), then open the graph and watch the concept wire itself in. Deploying with Portainer? Use docker-compose.portainer.yml as a repository stack.

Stack

pnpm monorepo:

Providers are configured through LLM_API_BASE_URL, LLM_API_KEY, LLM_API_FORMAT (openai or anthropic), and LLM_MODEL. Any OpenAI-compatible endpoint (DeepSeek, OpenAI, Groq, OpenRouter, llama.cpp, etc.) works with LLM_API_FORMAT=openai; Anthropic-compatible endpoints use LLM_API_FORMAT=anthropic. Optional fallback uses the matching LLM_FALLBACK_* variables.

llama.cpp

# on the inference box — --jinja enables OpenAI-style tool calling
llama-server -m model.gguf --jinja --host 0.0.0.0 --port 8080

# here — no model id needed, it's discovered for llama-server-like local endpoints
LLM_API_BASE_URL=http://inference-box:8080/v1 LLM_API_FORMAT=openai LLM_MODEL= \
BUNDLE_ROOT=./sample-bundle node packages/server/dist/index.js

Works behind llama-swap too: discovery prefers the currently loaded model so a query doesn't trigger a multi-minute model swap. Pin a specific model with LLM_MODEL=.

From source

pnpm install
pnpm build
cp .env.example .env   # add your API key

BUNDLE_ROOT=./sample-bundle \
LLM_API_BASE_URL=https://api.deepseek.com/v1 \
LLM_API_KEY=sk-... \
LLM_API_FORMAT=openai \
LLM_MODEL=deepseek-chat \
node packages/server/dist/index.js
# → http://localhost:3800  (web UI + /api + /mcp)

Or build the container yourself: docker compose up --build (the repo's docker-compose.yml builds from source and mounts ./sample-bundle).

Dev mode (server on :3800, Vite HMR on :5180 with proxy):

BUNDLE_ROOT=./sample-bundle pnpm --filter @understory/server dev
pnpm --filter @understory/web dev

MCP registration (Claude Code / Desktop)

claude mcp add ustory \
  -e BUNDLE_ROOT=/path/to/your/bundle \
  -e LLM_API_BASE_URL=https://api.deepseek.com/v1 \
  -e LLM_API_KEY=sk-... \
  -e LLM_API_FORMAT=openai \
  -e LLM_MODEL=deepseek-chat \
  -- node /path/to/understory/packages/server/dist/mcp/stdio.js

Or point an HTTP MCP client at http://host:3800/mcp.

Auth

By default the server is open — fine on localhost or a trusted LAN. Before exposing it anywhere else, set AUTH_TOKEN:

AUTH_TOKEN=$(openssl rand -hex 24)

With it set, /mcp and /api require Authorization: Bearer <token> (the web UI stays reachable and prompts for the token). Register authenticated MCP clients with a header:

claude mcp add --transport http ustory http://host:3800/mcp \
  --header "Authorization: Bearer <token>"

The stdio transport needs no token — it's a local process spawned by the client.

Profiles: several isolated memories on one server

One server can host a separate memory per profile, for example work, health and a side project. Each profile has its own bundle on disk and its own API key, and the key is the only thing that selects a memory. A request made with the work key is served from the work bundle and cannot name, read or search any other profile. The URLs stay the same for everyone.

Turn it on by pointing PROFILES_ROOT at a directory (it takes precedence over BUNDLE_ROOT):

services:
  understory:
    # ...as in the quick start, plus:
    volumes:
      - understory-profiles:/profiles
    environment:
      PROFILES_ROOT: /profiles
      ADMIN_TOKEN: ${ADMIN_TOKEN:-}   # optional, enables the /admin API

volumes:
  understory-profiles:

Manage profiles with the bundled CLI. It works against a running server, which picks up changes on the next request:

docker compose exec understory node server/dist/profiles-cli.js create work
# profile: work
# api key: usk_...        <- shown once; only a hash is stored

docker compose exec understory node server/dist/profiles-cli.js list
docker compose exec understory node server/dist/profiles-cli.js rotate work          # old key stops working
docker compose exec understory node server/dist/profiles-cli.js remove work          # revokes the key, keeps the memory
docker compose exec understory node server/dist/profiles-cli.js remove work --purge  # also deletes the memory

From a source checkout the same commands are PROFILES_ROOT=... pnpm --filter @understory/server profiles <command>.

Give each agent its profile's key:

claude mcp add --transport http work-memory http://host:3800/mcp \
  --header "Authorization: Bearer usk_..."

The web UI asks for a key and opens that profile's memory. The sidebar shows which profile you are in, with a switch button to enter a different key.

Things worth knowing:

• In profile mode every request needs a profile key. AUTH_TOKEN is not used.

• With ADMIN_TOKEN set, GET/POST /admin/profiles, POST /admin/profiles/<name>/rotate and DELETE /admin/profiles/<name>[?purge=true] do what the CLI does. The admin token manages profiles but cannot open any memory, and a profile key cannot reach /admin.

• Layout is PROFILES_ROOT/<name>/ per bundle plus PROFILES_ROOT/profiles.json for the registry. To move an existing bundle into a profile, put it at PROFILES_ROOT/<name>/ and run create <name>, which adopts the directory.

• The query cache, hot memory, traces, git history and dreaming are all per profile. Dreams run one profile after another.

• The stdio transport serves one bundle. Point its BUNDLE_ROOT at a profile's directory to use that memory locally.

Serving under a sub-path

The web UI uses relative URLs throughout, so it works behind a path-prefixing reverse proxy — no configuration needed. Any proxy that strips the prefix before forwarding works:

# Tailscale
tailscale serve --bg --set-path=/understory http://localhost:3800

# Caddy
handle_path /understory/* {
  reverse_proxy localhost:3800
}

One rule: open the UI with a trailing slash (https://host/understory/, not .../understory) — relative URLs resolve against the last path segment, so without the slash they escape the prefix. If your proxy can redirect /understory → /understory/, do that.

Seed memory

A client LLM that only sees four bare tool names never gets the instinct to check memory. So at session start the server injects a compact overview of what the knowledge base contains (directories, concepts with types + descriptions, recent activity) through both channels that reach the model:

1. the MCP initialize instructions field (clients like Claude put it in the system prompt), and

2. the memory_query tool description — the universal fallback every tool-calling client loads.

The seed regenerates fresh for every new session. After memory_add / memory_update in a long-lived (stdio) session, the tool description refreshes via tools/list_changed, so the session sees its own writes. Out-of-band edits (hand edits, other clients) are picked up on the next session.

Graph health & maintenance

Memory is a graph, not a pile of notes, and graphs rot: concepts go orphaned (nothing links to them) and links go broken. Two mechanisms keep it healthy:

• Write-time linking — new knowledge either enriches the concept it belongs to (an attribute of an existing entity is patched in, not filed separately) or, when it's a distinct entity, is created and back-linked from related concepts. Contradictions are superseded in place, never left standing alongside the old value.

• memory_maintain — a deterministic lint (orphans + broken links, surfaced in memory_status under graph) drives an internal agent to wire orphans into related concepts and fix dangling links. Run it periodically to counter drift; it's a no-op when the graph is already healthy.

This design mirrors the pattern in Karpathy's LLM Wiki (index.md + log.md, create-vs-enrich, lint for orphans). Deferred from that pattern until scale warrants: an explicit page-type schema, and hybrid FTS5+embedding search (the naive scan in search.ts is fine into the low thousands of concepts).

Tests

pnpm test                                  # core: 18 tests (spec §5/§6/§7/§9, sandbox, search, concurrency)
pnpm --filter @understory/server exec tsx scripts/mcp-smoke.mts   # MCP stdio round-trip (needs SMOKE_BUNDLE + an API key)

Environment

See .env.example. BUNDLE_ROOT is required; GIT_AUTOCOMMIT=true commits every mutation.