LiLara-AI/shadowgraph

**Local-first decision memory for AI agents.** ShadowGraph remembers what an agent decided, what it
rejected, why it rejected it, and when that decision should be reconsidered.
> Status: **Technical Preview / Early Access.** Install from GitHub — it is not on npm.
> See Limitations and Technical Preview status.
Why it matters
Chat memory remembers the conversation. It loses the decision.
Ask an agent three months later why the project uses SQLite and the useful part is already gone:
- The choice may survive in a summary. **The rejected alternative and the reason for rejecting it do not.**
- A fact changes — the deployment goes from single-user to multi-user — and **nothing reopens the decision.**
- The same approach fails again, because **the failed attempt was never recorded as a failed attempt.**
ShadowGraph stores that reasoning as structured, inspectable data instead of prose: what was chosen,
what was rejected, why, the assumptions and evidence behind it, failed attempts, outcomes,
provenance, confidence history, and the conditions that should trigger a rethink.
The promise is deliberately narrow: **important AI decisions should survive sessions and stay
explainable, reviewable, and reconsiderable.**
**Who it is for:** developers building agents on MCP, a CLI, or a local HTTP API who need
consequential decisions to outlive a session. It is a decision store, and it keeps its store on your
machine; data leaves the machine only through opt-ins you turn on (see
Local-first and privacy).
Quick Start — 5 minutes
Requirements
- Node.js 20+ (the optional SQLite backend needs Node 22.5+ for node:sqlite)
- No runtime npm dependencies, no build step, no account, no network calls
1. Install
ShadowGraph is **not published to npm**. During the Technical Preview, install it from this
repository. A global install puts shadowgraph on your PATH, which is what MCP clients need:
This installs the current main branch: the development build 0.42.0-dev.0, newer than the 0.41.0
Technical Preview and not a release. To install the Technical Preview instead, use
github:LiLara-AI/shadowgraph#v0.41.0. Before moving a store between the two, read
Moving between 0.41.0 and main.
Or clone and run from source
Replace shadowgraph with node src/cli.js in every command below.
> npm install shadowgraph-unified-plugin does **not** work and fails with E404. The package is
> private: true and unpublished, and the registry name is not reserved. This README will change if
> publication is ever approved.
2. JSON arguments and your shell
Every ShadowGraph command takes a single JSON argument, so **quoting depends on your shell.** Pick
the row for the shell you are actually using — this is the most common reason a first command fails:
| Shell | Form | Example |
| --- | --- | --- |
| bash / zsh / Git Bash (macOS, Linux, WSL) | single quotes, plain JSON | shadowgraph recall '{"project":"demo"}' |
| Windows PowerShell | single quotes, \" inside | shadowgraph recall '{\"project\":\"demo\"}' |
| Windows cmd.exe | double quotes, \" inside | shadowgraph recall "{\"project\":\"demo\"}" |
The examples below use the bash form. If a command fails in your shell, please report it.
3. Initialize a store
setup creates .shadowgraph/data.json in the current directory, so run it where you want the
store to live. It never rewrites an existing store. doctor then checks Node compatibility, storage
readability and writability, graph validity, and the MCP entry point.
Run setup **before** doctor: on a fresh directory doctor reports Storage is not initialized
and exits 1 until a store exists. That is expected, not a failed install.
4. Record a decision, restart, and get it back
Each command runs in a new process and reopens the store from disk, so the search result comes
back across a real restart, not from in-memory state. You now have a decision that carries its
rejected alternative, the reason it was rejected, and the condition that should reopen it.
The demo: a decision that reopens itself
This is the whole point of ShadowGraph, in three commands. Continue in the same directory.
**The decision is settled, so there is nothing to reconsider yet:**
**Now the world changes. The deployment becomes multi-user:**
**Restart and ask again — passing only the project, never the triggering fact:**
The result, abridged to the first fields of its one item:
ShadowGraph read the stored fact, matched it against the rule saved with the decision, and surfaced
the alternative that had been rejected for a reason that no longer holds. The full item also carries