ShadowGraph

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:

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

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.

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. If a command fails in your shell, please report it.

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"}'

{
  "items": [],
  "completeness": {
    "returned": 0,
    "total": 0,
    "omitted": 0,
    "complete": true,
    "losslessItems": true,
    "scope": {
      "project": "checkout-service",
      "requestState": "project_selected",
      "originPresented": false,
      "grant": null
    }
  }
}

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"}'

The result, abridged to the first fields of its one item:

{
  "items": [
    {
      "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. The full item also carries violatedConditions (each one names the stored fact it matched as evidence) and the review signal it recorded, and the result ends with a completeness block like the first one. Your IDs and times will differ.

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. Every write needs a project, a workspace binding (shadowgraph bind), or a capture-origin id: a write with none of them is refused (write_scope_unresolved) instead of landing in a shared default bucket, and default is an ordinary project name. search, retrieve, recall, context and traverse read only the selected project's own records, and the graph expansion they make stays in that project; with no project selected they return nothing, never every project and never a shared default bucket. An id outside the selected project -- or one that does not exist -- gets the same answer: no record. A new relationship joins two records of one project (link needs that project), and one across projects is refused like a missing endpoint; relationships stored across projects before are kept, and no read follows them. The journal, stats, redact's output and the public export (GET /records, list) read the same way. A by-id change -- an outcome, a status, confidence evidence, a supersession, a fact verification, a review acknowledgement -- changes only what its own project or origin owns, and answers another project's id exactly as a missing one. Saving, backup and restore still cover the whole store; the public export and a redaction are reads of one project and are refused as a store. Records written before schema 6 in default, or with no project, belong to no project a caller can name, so no project read returns them; the kernel's legacyAttributionReview() lists them for inspection, each with its legacy state and canonical record, and infers no project for them. A read with no project reports its empty result as incomplete (completeness.complete: false, with a scoped_coverage limitation), never as complete. The MCP tools, HTTP routes and CLI verbs pass the caller's project (or originId) to the same boundary: an outcome, a status change or a review acknowledgement sent with one changes only what it owns, and the same call without one is refused (write_scope_unresolved) alike for every id; stats over HTTP (GET /stats?project=...) and the CLI counts only the named project's content, and nothing without one. Wider access is explicit and revocable: an access grant the owner issues at a terminal (issue-access) opens the projects or origins it names to explicit reads that present it, until it expires or is revoked. It is not lesson-only sharing, and automatic hook delivery never uses one. A project name, like a presented origin id, is a selector, not access control: any caller of the CLI, MCP or HTTP API that names one explicitly reads it. Legacy records are what only a grant opens. See the access transport contract. Omitted scope means all-null scope. 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 opt-ins that can send data off the machine are all 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.
• Extraction. Separately approved extraction sends eligible redacted captures through the supported first-party Claude subscription route. No API-key, alternate-provider, proxy or paid fallback is supported by this executor; the owner must disable subscription overage. Pattern redaction cannot guarantee every secret is removed. Extraction runs only on Windows, with Claude Code 2.1.288, or with the profiled Claude Code 2.1.292 binary and the receipt of a passing real-host validation of it (ShadowGraph checks the receipt's identity, not the validation itself); on any other platform, version or binary it is refused. See extraction and its host limits.
• Markdown export. markdown-sync writes plaintext copies you control. ShadowGraph cannot find or delete those copies later — see Storage, backup, and deletion.
• Host delivery. Inert unless you install the hooks and activate delivery for one store. Once active, the records it delivers (credential-shaped values redacted first) become part of Claude Code's session transcript and of what the model receives, like any context; ShadowGraph cannot remove them from the transcript. See the integrations guide.

Capture, extraction and delivery require their separate activation procedures. Once active, capture records your prompts, tool calls with their input and output, and the assistant's text from Claude Code sessions, redacted by pattern, into a private local store. Capture uses the enrolled external store; existing manual stores are not automatically migrated, and delivery reads the one store its activation pins. Eligible uncited raw expires under the configured policy even when quarantined, while accepted experience and required cited evidence are protected. Expired raw may no longer be re-extracted.

See the data lifecycle map for deletion reach, retained copies, explicit Markdown pruning and recovery floors, and the integrated experience lifecycle for correction, reprocessing, restart and shutdown boundaries.

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 16 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

Tool metadata follows the revision initialize negotiates: a session negotiated at 2025-03-26 also receives behavioural annotations, and one at 2025-06-18 or 2025-11-25 also receives output schemas and structured results, while a session at 2024-11-05 keeps the tool members and serialized results it always had. A request for a revision this server does not implement is answered with 2025-11-25, the latest it does. See the MCP compatibility guide for the full table.

The 16 compact tools are shadowgraph_context, shadowgraph_review_context, shadowgraph_expand, shadowgraph_remember, shadowgraph_recall, shadowgraph_record_decision, shadowgraph_record_attempt, shadowgraph_record_fact, shadowgraph_record_outcome, shadowgraph_retrieve, shadowgraph_search, shadowgraph_review, shadowgraph_validate, shadowgraph_maintain, shadowgraph_ack_review — so a compact client can clear a review it can already see, instead of accumulating signals with no way to acknowledge them — and shadowgraph_reconsider, which reads the same evaluation as a verdict: review recommended, unchanged, or a human should look. shadowgraph_context is a read that persists nothing; shadowgraph_review_context persists the review signals it finds due, and shadowgraph_expand expands a claim line to its full record. Full mode advertises 35 — see the MCP compatibility guide for the complete inventory, every protocol revision, and verified client behaviour. Full mode includes owner tools: backup to a path the caller names, restore from one and purge. Its shadowgraph_bind and shadowgraph_attribute only propose: they change nothing and return the shadowgraph bind or attribute input the owner runs and confirms at a terminal. Give an agent compact mode unless you want it to have the owner tools (see SECURITY.md).

AI tool setup

Install globally first so the client can find shadowgraph on its PATH:

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

Claude Code (user scope):

claude mcp add --scope user --env SHADOWGRAPH_MCP_COMPACT=1 --transport stdio shadowgraph -- shadowgraph mcp

Cursor (.cursor/mcp.json or ~/.cursor/mcp.json):

{"mcpServers":{"shadowgraph":{"type":"stdio","command":"shadowgraph","args":["mcp"],"env":{"SHADOWGRAPH_MCP_COMPACT":"1"}}}}

Codex:

codex mcp add shadowgraph --env SHADOWGRAPH_MCP_COMPACT=1 -- shadowgraph mcp

Hermes Agent:

hermes mcp add shadowgraph --command shadowgraph --connect-timeout 30 --env SHADOWGRAPH_MCP_COMPACT=1 --args mcp

File forms for all four live in integrations/; npm run check:integrations validates them as files, which is not a live run of each client. Set an absolute SHADOWGRAPH_FILE in the client environment when one store must be shared across working directories.

CLI

The commands you will actually use:

shadowgraph setup
shadowgraph doctor
shadowgraph context '{"project":"my-app"}'
shadowgraph decision '{"project":"my-app","title":"Choose the datastore","chosen":"SQLite"}'
shadowgraph fact '{"project":"my-app","key":"deployment","value":"local","sourceClass":"human_confirmed"}'
shadowgraph attempt '{"project":"my-app","solution":"Rewrite everything","result":"Regression"}'
shadowgraph outcome '{"project":"my-app","decisionId":"DECISION_ID","outcome":{"status":"failed","lessons":["Assumption was wrong"]}}'
shadowgraph review '{"project":"my-app"}'
shadowgraph search '{"query":"database","project":"my-app"}'
shadowgraph remember '{"project":"my-app","memoryType":"preference","key":"editor","text":"Prefers VS Code"}'
shadowgraph recall '{"project":"my-app","query":"development environment"}'

HTTP API

shadowgraph serve
curl http://127.0.0.1:8787/health

A read-only dashboard is served at http://127.0.0.1:8787/dashboard. It talks only to the same local origin, and a token entered there is kept in page memory only — never in cookies, local storage, or ShadowGraph data.

GET  /health                 GET  /stats               GET  /records
GET  /search?q=&project=     GET  /review-signals      GET  /validate
GET  /journal

POST /decisions              POST /attempts            POST /memories
POST /recall                 POST /facts               POST /outcomes
POST /review                 POST /context             POST /status
POST /relationships          POST /traverse            POST /redact
POST /supersede              POST /maintain            POST /retrieve
POST /review-signals/ack     POST /repair-plan         POST /backup
POST /restore                POST /rebuild             POST /confidence-evidence
POST /projects/purge-preview

DELETE /projects

JavaScript

import { createShadowGraph } from 'shadowgraph-unified-plugin';

const graph = createShadowGraph();
graph.addDecision({
  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' }]
  }]
});
graph.addFact({
  project: 'checkout-service',
  key: 'deployment',
  value: 'multi-user',
  sourceClass: 'human_confirmed',
  confidence: 1
});

// review() reads stored facts, so this also works in a fresh process after an
// export/save and load. Do not pass the triggering fact again.
console.log(graph.review({ project: 'checkout-service' }));

The bare-specifier import resolves when ShadowGraph is a dependency of your project (npm install github:LiLara-AI/shadowgraph). With a --global install, use the CLI, HTTP, or MCP surfaces instead, or import from the installed path.

Storage, backup, and deletion

JSON is the zero-dependency default and stores a versioned graph in .shadowgraph/data.json. Set SHADOWGRAPH_FILE to relocate it. Set SHADOWGRAPH_STORAGE=sqlite on Node 22.5+ for the WAL-backed relational adapter. Stores are written at schema 7; schemas 1 through 6 remain readable, and downgrade forks a copy at schema 5 (the default, which 0.41.0 reads) or schema 6 (which only unreleased intermediate builds read), without changing the store.

State and journal are written in one atomic operation, every save and restore for a destination shares a cross-process lock fence, and a stale write is rejected with a revision conflict rather than silently lost. backup takes a consistent snapshot; restore validates domain and journal consistency before replacing live state, and rolls back on failure. This is process-level rollback safety, not a claim of crash or power-loss durability. The full guarantees — lock timeouts, stale-lock recovery, revision arithmetic, and restore artifact reporting — are in the API reference and the SQLite restore contract.

Deletion is explicit and previewable:

shadowgraph purge-preview '{"project":"release-demo"}'
shadowgraph purge '{"project":"release-demo"}'
shadowgraph purge '{"project":"another-project","mode":"hard"}'

Logical purge (the default) removes project content from the live projection and keeps an auditable, payload-free purge skeleton. Hard purge physically deletes journal entries, creates a declared gap, and cannot be undone.

Purge cannot delete external Markdown exports. ShadowGraph has no way to find plaintext copies in arbitrary workspaces, Git history, cloud sync, backups, or removable media. Delete those separately. Backups, the preservation and downgraded copies that migrate and downgrade write, and the recovery files an interrupted restore leaves can also still hold material purged or expired later; a purge does not reach them (see the data lifecycle map).

Limitations and Technical Preview status

The latest release is the 0.41.0 Technical Preview / Early Access (tag v0.41.0). It is not Beta and not stable. main carries 0.42.0-dev.0, a development build: not released, not stable, and its acceptance criteria have not been assessed.

• Interfaces and the storage schema may still change. Do not use it for data you cannot reproduce.
• Not on npm. The package is deliberately private: true. The v0.41.0 Git tag and GitHub Release are maintainer-authorized for this Technical Preview; npm publication is not authorized and has not occurred.
• No comparative benchmark has been measured. Comparative benchmark infrastructure was executed, but no arm was measured because no common local/free LLM and embedding endpoint was available. No comparative performance, quality, token, cost, or 'best' claim is supported. ShadowGraph makes no claim of being faster, cheaper, lower-token, more accurate, or better than any other memory system. See the benchmark report.
• Security review status. An AI-assisted independent security review of commit 4a5e076 (tree 62c1918e) was completed on 2026-08-30 by Antigravity Assistant (Gemini 3.7 Flash), with a PASS result and no unresolved findings. No human third-party security audit has been performed. See SECURITY.md. That review covered commit 4a5e076, before the v0.41.0 tag. Nothing added since has had an independent security review, including project scoping, access grants, deletion records and purge-aware restore, schema 6 and 7 migration and downgrade, the Claude Code hooks, automatic capture, transcript reading and extraction.
• Nothing is captured or extracted unless you turn it on, and there is no hosted sync. Without the optional Claude Code integration, ShadowGraph records what you tell it to record. With it, automatic capture of Claude Code sessions and model-based extraction each stay inert until the owner activates them separately; capture covers declared events only, with pattern-based redaction (see the integrations guide and extraction).
• Capture and delivery cover one enrolled store. Delivery reads the one store its activation pins, and capture writes the store it was enrolled with; other stores you use by hand are neither delivered nor captured into, and are not migrated.
• Single maintainer. No paid support, no patch SLA, and no bug bounty.

Moving between 0.41.0 and main

• Take a backup before upgrading. shadowgraph backup [<file>] copies the store: a JSON store byte for byte, a SQLite store table by table. A backup taken before this build first saves the store is still a schema-5 store that 0.41.0 opens. (Opening a SQLite store, this build adds a table of its own to it; 0.41.0 still reads the store.) Once this build has saved the store, its backups are schema-7 stores; to use one with 0.41.0, restore it into a fresh path with this build and fork a schema-5 copy as below.
• Upgrading. This build reads every store 0.41.0 wrote (schemas 1 through 5) and writes schema 7 on its next save. What changes for you:
  • A write that names no project is refused (write_scope_unresolved). Pass project, or bind the workspace to a project with shadowgraph bind.
  • Records 0.41.0 stored in default -- written without a project, which 0.41.0 put there, or naming default -- are legacy material whose owner this build treats as uncertain: no read returns them, not even with "project":"default". They are not deleted. The JavaScript API's legacyAttributionReview() lists them, and shadowgraph attribute '{"ids":["<id>"],"targetProject":"<project>","reason":"<why>"}', which you confirm at a terminal, moves named records into a project. To note their ids before upgrading, run 0.41.0's shadowgraph list, which prints every record, and keep the ids of those with "project": "default". If you rely on such records and do not want to move them, stay on 0.41.0.
  • Some results changed shape; for example, review returns {"items": [...], "completeness": {...}} instead of an array. The changelog lists every breaking change.
• Going back to 0.41.0. 0.41.0 reads schemas 1 through 5 only and refuses a store this build has saved. Fork a schema-5 copy with shadowgraph downgrade '{"output":"<new file>"}'. It first writes a verified preservation copy beside the store (<store>.preservation-<time>), then the copy, and never changes the store. <output>.report.json names what schema 5 cannot hold, such as record attribution, erasure tokens, claim evidence and capture state, and the copy's journal history is replaced by one baseline entry. Point 0.41.0 only at the copy: given a schema-7 SQLite store, 0.41.0 can set the file's journal mode before it refuses it.
• What 0.41.0 does not have. 0.41.0 has none of this build's project isolation or deletion records: there, a read that names no project returns every project's records, and restoring a backup taken before a purge brings the purged material back.
• Hooks, capture, delivery and extraction. 0.41.0 has no hook, capture, delivery or extraction commands. Before switching to it, run with this build shadowgraph deactivate extraction, shadowgraph deactivate capture, shadowgraph deactivate delivery, shadowgraph uninstall-hooks --capture and shadowgraph uninstall-hooks, and check that extraction's cleanup did not report deferred (see deactivate, uninstall and recover).

Feedback and support

Technical Preview feedback is the point of this release. Please tell us when something breaks.

During the preview, these reports are the most valuable:

• Installation problems — anything between npm install --global and a green doctor.
• MCP client compatibility — which client, which mode, and what it did or did not discover.
• Memory usefulness — did recalled context actually change what your agent did?
• Confusing workflows — where the docs or a command shape sent you the wrong way.
• Missing decision-memory use cases — decisions you wanted to store and could not.
• Performance — where it felt slow, and roughly how large the store was.

ShadowGraph has no telemetry and collects nothing automatically, so a report from you is the only signal there is. When pasting output, redact anything private: decision and memory content is your data, and shadowgraph doctor output is usually enough.

Documentation

Checks

npm run check
npm run test:performance
npm test
npm run check:integrations
npm run check:mcp
npm audit --omit=dev
npm run check:package
npm run smoke:package

GitHub Actions covers Ubuntu and Windows on Node 20, 22, and 24. In every job, the delivery-budget performance cases run in their own mandatory step before the suite. SQLite gates run only where node:sqlite exists. The strict official MCP Inspector runs full and compact gates, the pinned Glama mcp-proxy@6.4.3 gate proves the revision this server negotiates with it and that the tool list reaches an HTTP scanner unchanged, and the package smoke test runs from a real clean install in every matrix cell.

License

MIT. See LICENSE.