{"_id":"@asiaostrich/codesage","name":"@asiaostrich/codesage","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@asiaostrich/codesage","version":"0.1.0","description":"Open-source code + knowledge graph memory engine (SAGE + CodeGraph). AsiaOstrich is only a reference consumer.","license":"MIT","author":{"name":"AsiaOstrich"},"repository":{"type":"git","url":"git+https://github.com/AsiaOstrich/CodeSage.git"},"homepage":"https://github.com/AsiaOstrich/CodeSage#readme","bugs":{"url":"https://github.com/AsiaOstrich/CodeSage/issues"},"publishConfig":{"access":"public"},"type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"bin":{"codesage":"dist/cli/index.js","codesage-mcp":"dist/mcp/stdio.js"},"engines":{"node":">=22"},"scripts":{"build":"tsup","prepare":"tsup","health":"node poc/health-check.mjs","mcp":"node dist/mcp/stdio.js","test":"vitest run","test:watch":"vitest","typecheck":"tsc --noEmit","dev":"node --experimental-strip-types --watch src/api/dev-server.ts"},"keywords":["code-graph","knowledge-graph","kuzu","graph-memory","sage","tree-sitter"],"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","hono":"^4.6.0","kuzu":"^0.11.3","tree-sitter":"^0.22.4","tree-sitter-javascript":"^0.23.1","tree-sitter-typescript":"^0.23.2"},"devDependencies":{"@types/node":"^22.0.0","tsup":"^8.0.0","typescript":"^5.6.0","vitest":"^4.0.0"},"gitHead":"ef0915d29a66f6169ed78b6f34717034b9fe5fa5","_id":"@asiaostrich/codesage@0.1.0","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-BrDePFKXY9Raj+MmKbcrY9Ugt+acESUiyw5fwON4WyuBBx75LVAl9KOASS96Zy3Mmm+KAvpNB3yBN9TA6TUMuA==","shasum":"b065b61596ab33805e4989460cd6bd4bcd8d776e","tarball":"https://registry.npmjs.org/@asiaostrich/codesage/-/codesage-0.1.0.tgz","fileCount":27,"unpackedSize":6480327,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDWIxTmjCvkAVoGBMheH/C9Lc784HwMfRjTlYd3X8Cy8AiEAnYXv3S0D4t2EXnulOfFinSKuOpwPovLvjQ520TGhHB8="}]},"_npmUser":{"name":"asiaostrich","email":"asiaostrich@hotmail.com"},"directories":{},"maintainers":[{"name":"asiaostrich","email":"asiaostrich@hotmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/codesage_0.1.0_1780163865247_0.029047315604451285"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-30T17:57:45.091Z","0.1.0":"2026-05-30T17:57:45.475Z","modified":"2026-05-30T17:57:45.659Z"},"maintainers":[{"name":"asiaostrich","email":"asiaostrich@hotmail.com"}],"description":"Open-source code + knowledge graph memory engine (SAGE + CodeGraph). AsiaOstrich is only a reference consumer.","homepage":"https://github.com/AsiaOstrich/CodeSage#readme","keywords":["code-graph","knowledge-graph","kuzu","graph-memory","sage","tree-sitter"],"repository":{"type":"git","url":"git+https://github.com/AsiaOstrich/CodeSage.git"},"author":{"name":"AsiaOstrich"},"bugs":{"url":"https://github.com/AsiaOstrich/CodeSage/issues"},"license":"MIT","readme":"# CodeSage\n\n> **Language:** English · [繁體中文](./locales/zh-TW/README.md) · [简体中文](./locales/zh-CN/README.md)\n\n[![npm](https://img.shields.io/npm/v/@asiaostrich/codesage)](https://www.npmjs.com/package/@asiaostrich/codesage)\n[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n[![node](https://img.shields.io/badge/node-%E2%89%A522-brightgreen.svg)](https://nodejs.org)\n\n> Open-source **code + knowledge graph memory engine**, fusing\n> [SAGE](https://arxiv.org/abs/2605.12061) self-evolving graph memory with\n> CodeGraph structural code understanding.\n\n**License:** MIT · **Runtime:** Node.js ≥ 22 · **Graph DB:** [Kuzu](https://kuzudb.com/) (embedded, Cypher) · **No LLM required** (deterministic)\n\nCodeSage is a general-purpose engine. **AsiaOstrich (VibeOps / UDS / XSPEC / DEC)\nis only a reference consumer** — none of those concepts are baked into the core.\nThe defaults (\"single repo + generic markdown + git signals\") work out of the\nbox for any project; AsiaOstrich-specific behaviour is supplied through\npluggable adapters.\n\n## Why a graph?\n\nVector search (\"find me similar memories\") and graph traversal (\"find me\nstructurally related nodes\") are complementary. CodeSage adds the graph half:\n\n> \"I want to change `execute()` → the engine walks: callers → related specs →\n> the decisions behind them.\"\n\n## Install\n\n```bash\nnpm install @asiaostrich/codesage\n```\n\nOr run the CLI without installing:\n\n```bash\nnpx @asiaostrich/codesage index ./src\n```\n\n## Quickstart\n\n```bash\n# 1. Index a repo into the graph (code + optional docs)\ncodesage index ./src --docs\n\n# 2. \"What breaks if I change this function?\"\ncodesage callers myFunction --depth 2\n\n# 3. \"Which decisions sit behind this spec?\"\ncodesage impact XSPEC-237\n```\n\nThe graph DB lives at `CODESAGE_DB` (default `./.codesage/graph.db`).\nFull command reference: **[docs/CLI.md](./docs/CLI.md)**.\n\n### Embedded usage (in-process, zero HTTP)\n\n```ts\nimport { EmbeddedClient } from \"@asiaostrich/codesage\";\n\nconst client = new EmbeddedClient();   // SingleRepoIsolation by default\nawait client.init();                   // opens graph.db + ensures schema\nconst rows = await client.query(\"MATCH (f:Function) RETURN f.name AS name\");\nawait client.close();\n```\n\n### REST usage\n\n```ts\nimport { createServer, GraphConnection } from \"@asiaostrich/codesage\";\n\nconst conn = GraphConnection.open(\"./.codesage/graph.db\");\nconst app = createServer({ connection: conn });   // Hono app; routes under /graph/*\n// GET /health → { status: \"ok\" }\n```\n\nOr just `codesage serve --port 3000`. API reference: **[docs/API.md](./docs/API.md)**.\n\n## Three modes\n\n| Mode | Entry | Use case |\n|------|-------|----------|\n| **Embedded** | `EmbeddedClient` | Same-process, zero HTTP overhead (e.g. VibeOps integration) |\n| **REST** | `createServer()` (Hono) / `codesage serve` | Standalone graph service; routes under `/graph/*` |\n| **MCP** | `codesage-mcp` (stdio) / `codesage mcp` | Plug-and-play for coding assistants (Claude Code, Codex, Cursor, ...) |\n\n## MCP — use CodeSage from a coding assistant\n\nCodeSage ships an MCP server (stdio) exposing 5 tools — `index_code`,\n`index_docs`, `call_chain`, `impact_analysis`, `ingest_feedback` — so any\nMCP-capable assistant can use it as a code + knowledge graph. Zero LLM,\ndeterministic, **no Docker**.\n\n```bash\n# Claude Code, from an installed package:\nclaude mcp add codesage -- npx codesage-mcp\n```\n\nFull setup (Claude Code / Codex / Cursor / Windsurf), the 5 tools, and an\nexample flow: **[docs/MCP.md](./docs/MCP.md)**.\n\n## Core vs Adapter boundary\n\n| Layer | Contents | External usability |\n|-------|----------|--------------------|\n| **Generic Core** | CodeGraph (tree-sitter → graph), SAGE evolution, Kuzu abstraction, REST/MCP/Embedded modes, node-sdk | Zero AsiaOstrich dependency |\n| **Pluggable Adapters (interfaces)** | (1) knowledge source (2) isolation model (3) SAGE signal source | Core ships interface + a generic default |\n| **AsiaOstrich Reference Adapter** | XSPEC/DEC/ADR parser, org/project isolation, VibeOps test signals | Reference instances (not in core) |\n\n### The three adapters\n\n1. **Knowledge source** — `KnowledgeSource → { nodes, edges }`.\n   Default: `MarkdownKnowledgeSource` parses any front-matter markdown\n   (`id` / `title` / `status` + `[[ref]]` links) into generic `Doc` nodes.\n2. **Isolation model** — `IsolationModel.dbPath(ctx) → string`.\n   Default: `SingleRepoIsolation` (one `graph.db`, no org concept).\n   Opt-in: `OrgProjectIsolation` (`org-{orgId}/project-{projectId}/graph.db`).\n3. **SAGE signal source** — `SignalSource → FeedbackEvent[]`.\n   Defaults: `GitHistorySignalSource`, `TestExitCodeSignalSource`.\n\n## Graph schema\n\n6 node tables — `Function`, `Class`, `Module`, `Spec`, `Decision`, `Doc`.\n7 relationship tables — `CALLS`, `IMPORTS`, `DEFINES`, `IMPLEMENTS`, `IMPACTS`,\n`SUPERSEDES`, `REFERENCES`. See **[docs/API.md](./docs/API.md)** for the full DDL\nand the front-matter schema that drives knowledge ingestion.\n\n## Status\n\n- [x] **Phase 1** — scaffold (MIT, Node 22, ESM+CJS, tsup, vitest), Kuzu\n      abstraction + idempotent schema (6 NODE / 7 REL tables), three adapter\n      interfaces + generic defaults, Hono `GET /health`, `EmbeddedClient`\n- [x] **Phase 2** — CodeGraph: tree-sitter extractor/indexer, cross-file `CALLS`\n      resolution, scope-qualified function ids\n- [x] **Phase 3** — KnowledgeGraph: front-matter markdown → `Spec` / `Decision`\n      + `IMPACTS` / `SUPERSEDES` edges\n- [x] **Phase 4** — SAGE evolution layer: confidence feedback (`STEP` 0.25,\n      floor 0.1), `topByConfidence`, `rankedImpact`\n- [x] **Phase 5** — REST routes (`/graph/call-chain`, `/graph/impact-analysis`,\n      `/graph/ingest`), MCP server (5 tools), standalone `codesage` CLI\n\n## Contributing\n\nSee **[CONTRIBUTING.md](./CONTRIBUTING.md)** for dev setup, the build/test/health\nloop, and the kuzu + tree-sitter teardown caveat. Changes are tracked in\n**[CHANGELOG.md](./CHANGELOG.md)**.\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n","readmeFilename":"README.md","_rev":"1-fb7f2985e3ae5df3f743694b70be764b"}