{"_id":"2context","_rev":"2-e0d8d91faf24616b6015b2018f43aaac","name":"2context","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"2context","version":"0.1.0","keywords":["ai","knowledge-graph","context-engineering","developer-tools","cli"],"author":{"name":"Fabian Emilius"},"license":"MIT","_id":"2context@0.1.0","maintainers":[{"name":"fabian-emilius","email":"fabian.emilius@outlook.com"}],"homepage":"https://github.com/fabian-emilius/2context-cli#readme","bugs":{"url":"https://github.com/fabian-emilius/2context-cli/issues"},"bin":{"2context":"dist/main.js"},"dist":{"shasum":"033d050dc4c38de86e0276f8d49abc8cfea39817","tarball":"https://registry.npmjs.org/2context/-/2context-0.1.0.tgz","fileCount":137,"integrity":"sha512-wfdZkfoMKYse/KpDA9Bnt5w7DgUt33Spx9v9Ojoz6NEB8jFLsqK4+zHKS8FuAXtV0K+Y+q/qrzOqb49Hi2w0oA==","signatures":[{"sig":"MEYCIQDoJfpvJgiAy9sccjdC9hTFhhQkjQ73uZIOTaDVbyFJWgIhAKj5iOADog8yBkyKg9kjE2UQ5tYspcASWMSLgxh4JVJg","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":598899},"main":"dist/main.js","type":"module","engines":{"node":">=22.0.0"},"gitHead":"e3ad3d804bae0da49a6b83610f52e4d69a3ae268","scripts":{"lint":"eslint \"src/**/*.ts\" --fix","build":"nest build","format":"prettier --write \"src/**/*.ts\"","prepack":"npm run lint:check && npm run format:check","prepare":"npm run build","start:dev":"tsx src/main.ts","lint:check":"eslint \"src/**/*.ts\"","start:prod":"node dist/main.js","format:check":"prettier --check \"src/**/*.ts\"","prepublishOnly":"npm run build && npm run lint:check && npm run format:check"},"_npmUser":{"name":"fabian-emilius","email":"fabian.emilius@outlook.com"},"repository":{"url":"git+https://github.com/fabian-emilius/2context-cli.git","type":"git"},"_npmVersion":"10.9.4","description":"Turn your git history into structured knowledge — for your team and your AI tools.","directories":{},"_nodeVersion":"22.22.1","dependencies":{"ink":"^4.4.1","zod":"^3.24.0","rxjs":"^7.8.1","react":"^18.3.1","jsonrepair":"^3.13.3","simple-git":"^3.27.0","@mastra/core":"^1.10.0","@nestjs/core":"^11.0.0","@ai-sdk/google":"^1.0.0","@ai-sdk/openai":"^1.0.0","@nestjs/common":"^11.0.0","ink-text-input":"^5.0.1","nest-commander":"^3.15.0","ink-select-input":"^5.0.0","reflect-metadata":"^0.2.2","@ai-sdk/anthropic":"^1.0.0"},"preferGlobal":true,"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","eslint":"^8.57.1","@swc/cli":"^0.6.0","prettier":"^3.8.1","@swc/core":"^1.11.0","typescript":"^5.7.0","@nestjs/cli":"^11.0.0","@types/node":"^22.0.0","@types/react":"^18.3.28","eslint-config-prettier":"^10.1.8","eslint-plugin-prettier":"^5.5.5","@typescript-eslint/parser":"^8.57.2","eslint-plugin-unused-imports":"^4.4.1","@typescript-eslint/eslint-plugin":"^8.57.2","eslint-plugin-simple-import-sort":"^12.1.1"},"_npmOperationalInternal":{"tmp":"tmp/2context_0.1.0_1776780912821_0.17537113264494897","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"2context","version":"0.2.0","description":"Turn your git history into a structured knowledge base for your team and AI coding tools.","type":"module","main":"dist/main.js","bin":{"2context":"dist/main.js"},"license":"MIT","author":{"name":"Fabian Emilius"},"repository":{"type":"git","url":"git+https://github.com/fabian-emilius/2context-cli.git"},"homepage":"https://github.com/fabian-emilius/2context-cli#readme","bugs":{"url":"https://github.com/fabian-emilius/2context-cli/issues"},"preferGlobal":true,"keywords":["ai","knowledge-graph","context-engineering","developer-tools","cli"],"scripts":{"build":"nest build","lint":"eslint \"src/**/*.ts\" --fix","lint:check":"eslint \"src/**/*.ts\"","format":"prettier --write \"src/**/*.ts\"","format:check":"prettier --check \"src/**/*.ts\"","start:prod":"node dist/main.js","start:dev":"tsx src/main.ts","prepare":"npm run build","prepack":"npm run lint:check && npm run format:check","prepublishOnly":"npm run build && npm run lint:check && npm run format:check"},"dependencies":{"@ai-sdk/anthropic":"^1.0.0","@ai-sdk/google":"^1.0.0","@ai-sdk/openai":"^1.0.0","@mastra/core":"^1.10.0","@nestjs/common":"^11.0.0","@nestjs/core":"^11.0.0","ink":"^4.4.1","ink-select-input":"^5.0.0","ink-text-input":"^5.0.1","jsonrepair":"^3.13.3","nest-commander":"^3.15.0","react":"^18.3.1","reflect-metadata":"^0.2.2","rxjs":"^7.8.1","simple-git":"^3.27.0","zod":"^3.24.0"},"devDependencies":{"@nestjs/cli":"^11.0.0","@swc/cli":"^0.6.0","@swc/core":"^1.11.0","@types/node":"^22.0.0","@types/react":"^18.3.28","@typescript-eslint/eslint-plugin":"^8.57.2","@typescript-eslint/parser":"^8.57.2","eslint":"^8.57.1","eslint-config-prettier":"^10.1.8","eslint-plugin-prettier":"^5.5.5","eslint-plugin-simple-import-sort":"^12.1.1","eslint-plugin-unused-imports":"^4.4.1","prettier":"^3.8.1","tsx":"^4.21.0","typescript":"^5.7.0"},"engines":{"node":">=22.0.0"},"_id":"2context@0.2.0","gitHead":"78a034da87a790db1a690b8c874f9b6e7fa48364","_nodeVersion":"22.22.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-ToosHDYduBpxE6WBDO6K7CQIQWy28RQdQRlopYHFVOMvznQEiwrTMmXELGYFYcym8EL5D6Uu3u1vPj8nDIHIyA==","shasum":"4ade0044991b963e4bc973f1986e9d2c466f4bc4","tarball":"https://registry.npmjs.org/2context/-/2context-0.2.0.tgz","fileCount":143,"unpackedSize":678317,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCID4qxhsNlxCCtDmRsWLcZMLdqRlihrfkcOOefg4dX359AiBpcmeanlwInwrY0pvTAWDyAcMi0wwWdTIlW6C2fZGuSw=="}]},"_npmUser":{"name":"fabian-emilius","email":"fabian.emilius@gmail.com"},"directories":{},"maintainers":[{"name":"fabian-emilius","email":"fabian.emilius@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/2context_0.2.0_1777392144091_0.3926760658079844"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-21T14:15:12.820Z","modified":"2026-04-28T16:02:24.371Z","0.1.0":"2026-04-21T14:15:12.994Z","0.2.0":"2026-04-28T16:02:24.269Z"},"bugs":{"url":"https://github.com/fabian-emilius/2context-cli/issues"},"author":{"name":"Fabian Emilius"},"license":"MIT","homepage":"https://github.com/fabian-emilius/2context-cli#readme","keywords":["ai","knowledge-graph","context-engineering","developer-tools","cli"],"repository":{"type":"git","url":"git+https://github.com/fabian-emilius/2context-cli.git"},"description":"Turn your git history into a structured knowledge base for your team and AI coding tools.","maintainers":[{"name":"fabian-emilius","email":"fabian.emilius@gmail.com"}],"readme":"# 2context\n\n> A file-based knowledge graph for coding agents. Extracts decisions, conventions, and patterns from your git history and writes them as plain Markdown files that agents like Claude Code read directly.\n\n[![npm version](https://img.shields.io/npm/v/2context.svg)](https://www.npmjs.com/package/2context)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js ≥22](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org)\n\n---\n\n## What it is\n\nA CLI that builds and maintains a Markdown knowledge graph in your repo.\n\nCoding agents are stateless: they re-derive your conventions every session. 2context processes that context once (currently from your git commit history), classifies it, and writes it to disk where the agent can grep and read it with the tools it already has. No MCP server, no daemon, no API.\n\nOutput is plain files committed alongside your code:\n\n* **`.2context/KNOWLEDGE_GRAPH.md`** is the entry point. The agent is instructed to read this first.\n* **`.2context/graph/{category}/`** holds the central knowledge as a self-balancing tree, organized into four categories: `architecture`, `convention`, `decision`, `pattern`. Each folder contains an `_index.md` summarizing its children, plus leaf `.md` files that group related findings together.\n* **`KNOWLEDGE.md`** files sit next to the source folders they describe (e.g. `src/auth/KNOWLEDGE.md`).\n* A `## Knowledge Context` section is added to `CLAUDE.md` or `AGENTS.md` pointing the agent at the index.\n\n---\n\n## Sources\n\nThe current build ships with **one adapter: `git-commits`**. The pipeline is built around a generic adapter interface, so additional sources can feed the same graph without changing how the agent consumes it. Pull requests, ADRs, issue threads, and custom sources are on the roadmap.\n\n---\n\n## Quickstart\n\n```bash\nnpm install -g 2context\ncd /path/to/your-repo\n2context init\n```\n\nFirst run walks you through provider selection (Anthropic, OpenAI, or Google) and API key entry, then ingests your full history. Keys are stored in `~/.2context/keys.json` (chmod 600).\n\nAfter the first run, use `2context ingest` to pick up new commits incrementally.\n\n---\n\n## How it works\n\nEach `ingest` run goes through these phases:\n\n1. **Fetch.** Read commits since the last cursor (or all commits with `--force`). Skip merges, dependency bumps, and formatting-only diffs.\n2. **Cluster and extract.** An LLM groups related commits into feature units, then reads the diffs and produces `KnowledgeItem`s with category, summary, content, and source provenance (commit SHAs, files touched).\n3. **Insert into the index.** Each general-scope item is routed top-down through the central tree by an LLM at every branch — using each child's summary to pick the next hop, or to create a new sibling when nothing fits. The item lands in a leaf `.md` file alongside other related findings. Co-located items go straight to the matching source-tree `KNOWLEDGE.md`.\n4. **Self-balance on insert.** After each insertion, the index walks back up to the root: leaves that exceed the per-leaf threshold (item count or rendered byte size) are split into topical sibling leaves; branches that exceed the per-branch child cap are split into intermediate sub-branches. Every touched node has its summary regenerated so subsequent routing stays accurate. The standalone `2context rebalance` command runs the same checks across the whole tree on demand.\n5. **Update agent file.** The `## Knowledge Context` section in `CLAUDE.md` / `AGENTS.md` is regenerated, telling the agent to read `.2context/KNOWLEDGE_GRAPH.md` before starting any task.\n\nState for each adapter lives in `.2context/sources/{adapter-id}/state.json` so the next run only processes what is new.\n\n---\n\n## Commands\n\n### `2context init`\n\nConfigure the AI provider, scaffold `.2context/`, and run the first ingest.\n\n```\n-b, --branch <name>   Branch to analyze (default: main/master)\n-v, --verbose         Verbose output\n```\n\n### `2context ingest`\n\nRun the ingestion pipeline. Incremental by default.\n\n```\n-b, --branch <name>   Branch to analyze\n-f, --force           Wipe items and reprocess from scratch\n-s, --source <id>     Run a single adapter only (e.g. git-commits)\n    --no-rebalance    Skip the post-ingest rebalance step\n-v, --verbose         Verbose output\n```\n\n### `2context status`\n\nPrint configuration, item counts per category, source cursor positions, and co-located files.\n\n### `2context validate`\n\nCheck stored items against their sources. For `git-commits`, this verifies referenced files still exist and source commits are reachable. Items get marked stale on a miss and removed after two consecutive stale verdicts. Rebuilds the index on completion.\n\n```\n--dry-run    Report removals without writing\n-v, --verbose\n```\n\n### `2context rebalance`\n\nSweep the entire central tree: re-cluster overfull leaves and branches, regenerate every node's summary. The index already self-balances on every insert during `ingest`; this command is for manual reorganization, e.g. after threshold changes.\n\n```\n--dry-run    Show proposed splits/merges without changing anything\n-v, --verbose\n```\n\n---\n\n## Output structure\n\n```\nyour-repo/\n├── .2context/\n│   ├── KNOWLEDGE_GRAPH.md             # Entry point. Agent reads this first.\n│   ├── graph/\n│   │   ├── architecture/\n│   │   │   ├── _index.md              # Folder summary + child outline\n│   │   │   ├── api-design/            # Sub-branch created on insert when siblings cluster\n│   │   │   │   ├── _index.md\n│   │   │   │   └── versioning.md      # Leaf — multiple findings grouped by topic\n│   │   │   └── caching.md             # Leaf — sits directly under architecture/\n│   │   ├── convention/\n│   │   │   └── _index.md\n│   │   ├── decision/\n│   │   │   └── _index.md\n│   │   └── pattern/\n│   │       └── _index.md\n│   └── sources/\n│       └── git-commits/state.json     # Cursor (gitignored)\n├── src/\n│   ├── auth/\n│   │   ├── KNOWLEDGE.md               # Co-located items for this folder\n│   │   └── jwt.ts\n│   └── db/\n│       └── KNOWLEDGE.md\n└── CLAUDE.md                          # Auto-updated Knowledge Context section\n```\n\nEvery `_index.md` and leaf `.md` carries YAML frontmatter (id, summary, keywords, parent, children/items) so a navigating agent can drill down a level at a time using only summaries — no need to read the full graph.\n\n**Commit:** `.2context/KNOWLEDGE_GRAPH.md`, `.2context/graph/`, `src/**/KNOWLEDGE.md`, `CLAUDE.md` / `AGENTS.md`.\n**Don't commit:** `.2context/sources/` (cursor state, already gitignored).\n\n---\n\n## Configuration\n\nResolution order: env vars → `~/.2context/keys.json` → interactive wizard.\n\n```bash\nexport TWOCONTEXT_PROVIDER=anthropic        # anthropic | openai | google\nexport ANTHROPIC_API_KEY=sk-ant-...\nexport OPENAI_API_KEY=sk-...\nexport GOOGLE_GENERATIVE_AI_API_KEY=...\n\n# Optional\nexport TWOCONTEXT_MODEL=anthropic/claude-opus-4-7\nexport TWOCONTEXT_CI=true                   # plain-text output, no prompts\n```\n\n| Provider | Default | Other models |\n|----------|---------|--------------|\n| Anthropic | `claude-sonnet-4-6` | `claude-haiku-4-5`, `claude-opus-4-7` |\n| OpenAI | `gpt-4o` | `gpt-4o-mini`, `o3-mini` |\n| Google | `gemini-2.5-flash` | `gemini-2.5-pro`, `gemini-2.0-flash` |\n\n---\n\n## CI usage\n\n```yaml\n- name: Update knowledge graph\n  env:\n    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}\n  run: |\n    npm install -g 2context\n    2context ingest\n    git add .2context CLAUDE.md src/**/KNOWLEDGE.md\n    git commit -m \"chore: update knowledge graph\" || true\n    git push\n```\n\n---\n\n## Contributing\n\n```bash\ngit clone https://github.com/fabian-emilius/2context-cli\ncd 2context-cli\nnpm install\nnpm run start:dev -- init        # dev mode (tsx)\nnpm run build && npm run start:prod -- status\nnpm run lint && npm run format\n```\n\nPull requests welcome. Open an issue first for significant changes, especially new adapters.\n\n---\n\n[MIT](./LICENSE) · Copyright (c) 2026 Fabian Emilius\n","readmeFilename":"README.md"}