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, not a transcript store, and it keeps everything on your machine.

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:

npm install --global github:LiLara-AI/shadowgraph

git clone https://github.com/LiLara-AI/shadowgraph.git
cd shadowgraph
npm install
node src/cli.js setup
node src/cli.js doctor

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:

The examples below use the bash form. All three are tested on every command in this README.

3. Initialize a store

mkdir shadowgraph-demo
cd shadowgraph-demo
shadowgraph setup
shadowgraph doctor

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

shadowgraph decision '{"project":"checkout-service","title":"Choose the datastore","chosen":"SQLite","confidence":0.8,"alternatives":[{"label":"PostgreSQL","reasonRejected":"Single-user local deployment does not justify running a server","reopenWhen":[{"key":"deployment","operator":"equals","value":"multi-user"}]}]}'

shadowgraph fact '{"project":"checkout-service","key":"deployment","value":"single-user","sourceClass":"human_confirmed","confidence":1}'

shadowgraph search '{"query":"datastore","project":"checkout-service"}'

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:

shadowgraph review '{"project":"checkout-service"}'

[]

Now the world changes. The deployment becomes multi-user:

shadowgraph fact '{"project":"checkout-service","key":"deployment","value":"multi-user","sourceClass":"human_confirmed","confidence":1}'

Restart and ask again — passing only the project, never the triggering fact:

shadowgraph review '{"project":"checkout-service"}'

[
  {
    "decisionId": "decision_1788079304730_yjawcg",
    "title": "Choose the datastore",
    "reason": "deployment",
    "alternativesToReconsider": [
      "PostgreSQL"
    ]
  }
]

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. Your decision IDs will differ; nothing else does.

That is decision memory: not "what did we talk about", but "what did we decide, what did we rule out, and does that still hold?"

For the same story through MCP, the HTTP API, and the JavaScript API — plus recording failed attempts and outcomes — see the decision-memory demo.

Key capabilities

Decision memory. Decisions carry the chosen approach, rejected alternatives with their reasons, assumptions, evidence, and structured reopenWhen rules. Outcomes (successful, mixed, failed, unknown) feed back into confidence.

Reconsideration. review() evaluates reopen rules against stored facts, so it works after a restart without the caller re-supplying what changed. Review signals are persisted and acknowledgeable.

Failed-attempt memory. Attempts record the approach, the result, the environment, and the lesson, so an agent can discover that something was already tried and why it did not work.

Provenance you can audit. Every claim carries a sourceClass — agent_claimed, tool_observed, human_confirmed, or production_verified — which records what was claimed about an observation's origin, never proof of it. Ordinary tool input cannot create verified; that requires a separately configured Ed25519 verifier.

Scoped memory and temporal recall. remember() / recall() store preferences, profiles, goals, instructions, procedures, episodes, and notes under a project plus optional userId / agentId / runId. Facts, memories, and relations are bi-temporal, so you can ask what was true asOf a past moment. Retrieval fuses lexical, vector, graph-distance, and temporal signals and declares which signals were unavailable rather than silently degrading.

Project and scope isolation. Omitted project and scope mean the default project and all-null scope — never every project or every user. Purge is previewable, logical by default, and explicitly irreversible in hard mode.

Explainable retrieval. Results expose raw scores, ranks, and reasons, and every bounded response declares its total, pages, and omitted scope. Nothing is silently summarized away.

Local-first and privacy

Everything is a local file. The HTTP server binds to 127.0.0.1 and rejects non-local browser origins. There is no cloud service, no account, no telemetry, and no analytics — ShadowGraph makes no outbound network request unless you explicitly configure one.

The two opt-ins that can send data off the machine are both off by default:

• Embeddings. No endpoint is configured. A localhost OpenAI-compatible server works once configured; a remote endpoint additionally requires SHADOWGRAPH_ALLOW_REMOTE_EMBEDDINGS=1, because that means memory and query text leave your machine.
• Markdown export. markdown-sync writes plaintext copies you control. ShadowGraph cannot find or delete those copies later — see Storage, backup, and deletion.

For shared local use, set a Bearer token:

SHADOWGRAPH_API_TOKEN="use-a-random-token-at-least-16-characters" shadowgraph serve

Then send Authorization: Bearer use-a-random-token-at-least-16-characters with every request. This is defense in depth for a local deployment, not a public-internet security model. See SECURITY.md.

Interfaces

MCP

shadowgraph mcp

Compact mode is recommended: it advertises 12 workflow tools while the full graph, memories, facts, alternatives, and outcomes stay stored at full fidelity. Compact mode is a tool-advertisement choice, not lossy storage.

SHADOWGRAPH_MCP_COMPACT=1 shadowgraph mcp