Content
# EngramGraph
> **Language:** English · [繁體中文](./locales/zh-TW/README.md) · [简体中文](./locales/zh-CN/README.md)
[](https://www.npmjs.com/package/engramgraph)
[](./LICENSE)
[](https://nodejs.org)
> Open-source **code + knowledge graph memory engine**, fusing
> [SAGE](https://arxiv.org/abs/2605.12061) self-evolving graph memory with
> CodeGraph structural code understanding.
**License:** MIT · **Runtime:** Node.js ≥ 22 · **Graph DB:** [Kuzu](https://kuzudb.com/) (embedded, Cypher) · **No LLM required** (deterministic)
EngramGraph is a general-purpose engine. The defaults ("single repo + generic
markdown + git signals") work out of the box for any project; project-specific
behaviour is supplied through pluggable adapters.
## Why a graph?
Vector search ("find me similar memories") and graph traversal ("find me
structurally related nodes") are complementary. EngramGraph adds the graph half:
> "I want to change `execute()` → the engine walks: callers → related specs →
> the decisions behind them."
## Install
```bash
npm install -g engramgraph
```
This puts the `egr` CLI on your `PATH` so the Quickstart commands below work from
any directory. Or run the CLI without a global install:
```bash
npx engramgraph index ./src
```
## Quickstart
```bash
# 1. Index a repo into the graph (code + optional docs)
egr index ./src --docs
# 2. "What breaks if I change this function?"
egr callers myFunction --depth 2
# 3. "Which decisions sit behind this spec?"
egr impact SPEC-001
```
The graph DB lives at `ENGRAM_DB` (default `./.engram/graph.db`).
Full command reference: **[docs/CLI.md](./docs/CLI.md)**.
### Embedded usage (in-process, zero HTTP)
> **Library use** (Embedded / REST below) needs a local dependency, not the
> global CLI — install with `npm install engramgraph` (no `-g`) so
> `import ... from "engramgraph"` resolves.
```ts
import { EmbeddedClient } from "engramgraph";
const client = new EmbeddedClient(); // SingleRepoIsolation by default
await client.init(); // opens graph.db + ensures schema
const rows = await client.query("MATCH (f:Function) RETURN f.name AS name");
await client.close();
```
### REST usage
```ts
import { createServer, GraphConnection } from "engramgraph";
const conn = GraphConnection.open("./.engram/graph.db");
const app = createServer({ connection: conn }); // Hono app; routes under /graph/*
// GET /health → { status: "ok" }
```
Or just `egr serve --port 3000`. API reference: **[docs/API.md](./docs/API.md)**.
## Three modes
| Mode | Entry | Use case |
|------|-------|----------|
| **Embedded** | `EmbeddedClient` | Same-process, zero HTTP overhead (e.g. same-process integration) |
| **REST** | `createServer()` (Hono) / `egr serve` | Standalone graph service; routes under `/graph/*` |
| **MCP** | `egr-mcp` (stdio) / `egr mcp` | Plug-and-play for coding assistants (Claude Code, Codex, Cursor, ...) |
## MCP — use EngramGraph from a coding assistant
EngramGraph ships an MCP server (stdio) exposing 5 tools — `index_code`,
`index_docs`, `call_chain`, `impact_analysis`, `ingest_feedback` — so any
MCP-capable assistant can use it as a code + knowledge graph. Zero LLM,
deterministic, **no Docker**.
```bash
# Claude Code, from an installed package:
claude mcp add egr -- npx egr-mcp
```
Full setup (Claude Code / Codex / Cursor / Windsurf), the 5 tools, and an
example flow: **[docs/MCP.md](./docs/MCP.md)**.
## Core vs Adapter boundary
| Layer | Contents | External usability |
|-------|----------|--------------------|
| **Generic Core** | CodeGraph (tree-sitter → graph), SAGE evolution, Kuzu abstraction, REST/MCP/Embedded modes, node-sdk | Zero project-specific dependency |
| **Pluggable Adapters (interfaces)** | (1) knowledge source (2) isolation model (3) SAGE signal source | Core ships interface + a generic default |
### The three adapters
1. **Knowledge source** — `KnowledgeSource → { nodes, edges }`.
Default: `MarkdownKnowledgeSource` parses any front-matter markdown
(`id` / `title` / `status` + `[[ref]]` links) into generic `Doc` nodes.
2. **Isolation model** — `IsolationModel.dbPath(ctx) → string`.
Default: `SingleRepoIsolation` (one `graph.db`, no org concept).
Opt-in: `OrgProjectIsolation` (`org-{orgId}/project-{projectId}/graph.db`).
3. **SAGE signal source** — `SignalSource → FeedbackEvent[]`.
Defaults: `GitHistorySignalSource`, `TestExitCodeSignalSource`.
## Graph schema
6 node tables — `Function`, `Class`, `Module`, `Spec`, `Decision`, `Doc`.
7 relationship tables — `CALLS`, `IMPORTS`, `DEFINES`, `IMPLEMENTS`, `IMPACTS`,
`SUPERSEDES`, `REFERENCES`. See **[docs/API.md](./docs/API.md)** for the full DDL
and the front-matter schema that drives knowledge ingestion.
## Status
- [x] **Phase 1** — scaffold (MIT, Node 22, ESM+CJS, tsup, vitest), Kuzu
abstraction + idempotent schema (6 NODE / 7 REL tables), three adapter
interfaces + generic defaults, Hono `GET /health`, `EmbeddedClient`
- [x] **Phase 2** — CodeGraph: tree-sitter extractor/indexer, cross-file `CALLS`
resolution, scope-qualified function ids
- [x] **Phase 3** — KnowledgeGraph: front-matter markdown → `Spec` / `Decision`
+ `IMPACTS` / `SUPERSEDES` edges
- [x] **Phase 4** — SAGE evolution layer: confidence feedback (`STEP` 0.25,
floor 0.1), `topByConfidence`, `rankedImpact`
- [x] **Phase 5** — REST routes (`/graph/call-chain`, `/graph/impact-analysis`,
`/graph/ingest`), MCP server (5 tools), standalone `egr` CLI
## Contributing
See **[CONTRIBUTING.md](./CONTRIBUTING.md)** for dev setup, the build/test/health
loop, and the kuzu + tree-sitter teardown caveat. Changes are tracked in
**[CHANGELOG.md](./CHANGELOG.md)**.
## License
MIT — see [LICENSE](./LICENSE).
