understory: an agent-managed markdown memory bundle, checked by code
understory — memory that grows. Self-wiring, plain-markdown memory for AI agents (MCP + local models + a living graph).
At a glance
- What is it?
- understory gives an agent five MCP tools over a directory of plain markdown files that follows the Open Knowledge Format spec. The model decides what to write; a deterministic layer validates the frontmatter, regenerates the indexes and sandboxes every path, so a bad write fails a test rather than corrupting the bundle.
- Who is it for?
- understory fits teams that want agent memory they can read, diff and keep in git, and that do not want to hand a model write access to an unvalidated store. It does not fit a single session or a throwaway agent, since a bundle, an index and a log are the whole point.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 31 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- thecodacus/understory348 ★ · +22
| Repository | 2026-09-19 | 2026-11-15 |
|---|---|---|
| thecodacus/understory | 326 | 348 |
22 Stars in the last 57 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Conformance lives in the bundle layer, not the prompt
The design rule the project states outright is that conformance is enforced in code rather than in prompts, and the split is visible in the package layout. packages/core holds the OKF bundle layer, which is described as having zero LLM involvement, plus the agent itself and a provider registry. packages/server is Express, serving MCP over streamable HTTP at /mcp, a stdio binary, a REST browse API under /api, streaming chat at /api/chat, and the built web assets. packages/web is the Vite and React front end with Tailwind.
What the deterministic layer actually does is concrete: it validates frontmatter and requires a type field, it regenerates index.md files, it appends entries to log.md newest first as the spec's section 7 requires, and it sandboxes all paths to the bundle root. So the model chooses what changes and the code decides whether the result is a valid bundle. Bundles follow the Open Knowledge Format v0.1 spec, which means plain markdown files with YAML frontmatter that stay readable to a human and diffable in git.
Five MCP tools, each one a full agent run
The MCP surface is five tools: memory_query, memory_add, memory_update, memory_status and memory_maintain. They arrive over stdio or over streamable HTTP, and the design note worth knowing is that each call drives an internal LLM agent with the OKF spec sitting in its system prompt. There is no fast path where a tool call is a database insert; every operation is an agent turn that happens to be bounded by a tool schema.
The agent's own loop is a Vercel AI SDK tool loop over six operations: search, read, list, write, patch and delete. Registering the server from Claude Code looks like this:
claude mcp add --transport http ustory http://localhost:3800/mcpAfter registration the agent also receives a seed overview of the memory at the start of every session. The web UI exposes the same agent for testing, and it renders tool calls inline so you can watch the searches and reads happen rather than infer them from the answer. There is also a CLI path, pnpm agent:query and pnpm agent:mutate, described as smoke entries rather than a full interface.
Every run leaves a replayable trace
Each agent run, whether it came from a query, a mutation or a chat message, records the path it took through the memory: the searches it ran, the concepts it read, the concepts it wrote. The notation is compact and it is persisted under a .traces directory inside the bundle, so it travels with the data rather than living in a log somewhere else.
The graph view is where this pays off. It lists recent runs, and selecting one replays that run's traversal as numbered directed hops over the force-directed graph: visited concepts get ringed, search hits are dotted, and everything else fades back. The same view draws orphans in red and sizes nodes by connection count, which makes the two questions you actually care about answerable visually. Did the agent read the concept I expected, or did it wander through six search hits first? Which concepts have no incoming links at all? For a memory system, being able to answer those from a replay is worth more than another chat feature.
An unset AUTH_TOKEN leaves the API open
The compose file and the example environment file treat authentication as optional, which is the one default worth arguing with. AUTH_TOKEN defaults to an empty string, and the comment in the example file says that leaving it unset means open, which is fine for localhost or a trusted LAN, and that you should set it before exposing the server anywhere else. When it is set, both /mcp and /api require an Authorization header with a bearer token.
The same file makes a few other defaults explicit. GIT_AUTOCOMMIT defaults to false, and when enabled it commits bundle changes to git after each mutation, which turns every memory write into a commit and gives you an audit trail at the cost of repository noise. PORT defaults to 3800. The primary model configuration is four variables, base URL, key, format and model, with the format set to openai or anthropic, and the legacy per-provider key variables are still accepted for backward compatibility while being marked deprecated.
Inside the container, localhost means the container
The quickest way to run the project is the published image, and the compose file the documentation asks you to save has three details that matter. The service publishes port 3800, it maps host.docker.internal to the host gateway so the container can reach a model server running on your machine, and it mounts a named volume at /bundle with BUNDLE_ROOT pointed there. Your memory is therefore plain markdown in a Docker volume, not a database.
docker compose up -dThe gateway mapping exists for one reason, stated plainly in the documentation: when understory runs in Docker, localhost is the container itself rather than the host, so a llama-server on the host has to be addressed at host.docker.internal, and running from source on the same box uses http://localhost:8080/v1 instead. The image is ghcr.io/thecodacus/understory:latest. If you deploy with Portainer, a separate compose file in the repository is set up as a stack. A second compose file in the repository builds from source and bind mounts ./sample-bundle instead.
Fallback fires on retryable errors, and can be read only
Provider configuration is uniform enough that provider selection is mostly a matter of three variables. Any OpenAI-compatible endpoint works with LLM_API_FORMAT set to openai, which covers DeepSeek, OpenAI, Groq, OpenRouter and llama.cpp, while Anthropic-compatible endpoints use the anthropic format. The documented examples pair a base URL, a key and a model id, such as deepseek-chat for DeepSeek, gpt-4o for OpenAI, llama-3.3-70b-versatile for Groq and claude-sonnet-5 for Anthropic.
The fallback set is separate and conditional. The example file says the fallback model is used when the primary fails with a retryable error such as a timeout or a 5xx, and that leaving LLM_FALLBACK_API_BASE_URL empty disables it. One flag narrows it further: LLM_FALLBACK_ALLOW_FOR defaults to query, so by default a fallback model handles read operations and not writes. That default is the sensible one, since a read answered by a weaker model costs you nothing but a write answered by a weaker model can damage the bundle.
Query cache and hot memory buy latency with freshness
Two optional features sit between a query and the agent, and both are off until you ask for them. QUERY_CACHE makes repeated memory_query questions answer from cache until the bundle changes, so an agent that asks the same thing twice pays once. QUERY_CACHE_TTL accepts a duration such as 1h, and the default is 24h; setting QUERY_CACHE to false disables the behaviour outright.
HOT_MEMORY is the subtler one. Recent writes and recent answers form a working set, and a query checks that set with one cheap tool-free LLM call before committing to the full agent run. Its TTL defaults to 1h. The trade is the same in both cases: you are trading the chance that the answer reflects something that just changed for a shorter path, and the cache key is invalidated by bundle changes rather than by time alone. A third feature, described as dreaming, is autonomous memory consolidation on an interval and is opt-in as well.
The Dockerfile ships only the server into runtime
The image is a two stage build on node:22-alpine, and the staging is deliberate. The build stage enables corepack, copies only the workspace manifests and each package's package.json, runs pnpm install with the frozen lockfile, then copies the sources and builds. It finishes with a pnpm deploy of the server package into a directory that survives into the second stage, which means the runtime image does not need the workspace or the dev dependencies.
The runtime stage sets NODE_ENV to production with BUNDLE_ROOT at /bundle and PORT at 3800, exposes 3800, declares /bundle as a volume, and starts node server/dist/index.js. The web build is copied in separately, so the browser interface and the agent server ship in one process tree. Outside Docker the package manifest asks for Node 20 or newer and pins pnpm 10.15.0 as the package manager, with scripts that fan out across the workspace for test, build and dev, and dev mode puts the server on 3800 with Vite hot reload on 5180 behind a proxy. The manifest still reads version 0.1.0 and the repository has no published releases yet.
Editorial conclusion
understory fits teams that want agent memory they can read, diff and keep in git, and that do not want to hand a model write access to an unvalidated store. It does not fit a single session or a throwaway agent, since a bundle, an index and a log are the whole point. Before you put it on a network, set AUTH_TOKEN, because the default is an unauthenticated /mcp and /api, and before you trust the retrieval, look at a trace under .traces to see whether the agent read the concept you expected or wandered off through search hits. Decide about the query cache and hot memory flags explicitly too, because both trade freshness for speed and neither is on by default.
Frequently asked questions
What does understory's memory look like on disk?
Plain markdown files with YAML frontmatter following the Open Knowledge Format v0.1 spec. The bundle layer requires a type field in frontmatter, regenerates index.md files and appends log.md entries newest first, all inside a bundle root directory.
Which MCP tools does understory expose?
memory_query, memory_add, memory_update, memory_status and memory_maintain, over stdio or streamable HTTP. The streamable endpoint is http://localhost:3800/mcp and each call runs an internal agent with the OKF spec in its system prompt.
Do I need a hosted model to run understory?
No. Any OpenAI-compatible or Anthropic-compatible endpoint works, and a local llama-server is supported with model discovery that prefers the currently loaded model. Inside Docker the host is reached at host.docker.internal rather than localhost.
Is understory safe to expose on a network?
Only if you set AUTH_TOKEN. It is optional and unset means open, which the example environment file calls fine for localhost or a LAN; when set, it requires a bearer Authorization header on both /mcp and /api.
What does GIT_AUTOCOMMIT do in understory?
When enabled it commits bundle changes to git after each mutation, so every memory write becomes a commit. It defaults to false in both the example environment file and the compose file.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/thecodacus-understory)Star history chart for your README
[](https://hysenlabs.com/projects/thecodacus-understory)Was this useful?