cortex-kg 0.1.0__tar.gz

cortex_kg-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roshan Gamage
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cortex_kg-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include LICENSE
+include README.md
+include pyproject.toml
+recursive-include docs *.md *.mdc *.json
+recursive-include examples *
+recursive-include sdk *
+global-exclude __pycache__ *.py[cod] .DS_Store
+prune .venv
+prune tests

cortex_kg-0.1.0/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: cortex-kg
+Version: 0.1.0
+Summary: Cortex: a persistent, workspace-level Engineering Knowledge Graph.
+Author-email: Roshan Gamage <roshangamage01@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/RoshanGamage01/Cortex
+Project-URL: Repository, https://github.com/RoshanGamage01/Cortex
+Project-URL: Documentation, https://github.com/RoshanGamage01/Cortex/tree/main/docs
+Project-URL: Issues, https://github.com/RoshanGamage01/Cortex/issues
+Project-URL: Changelog, https://github.com/RoshanGamage01/Cortex/releases
+Keywords: knowledge-graph,mcp,engineering,ai,local-first,rag,cursor
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: kuzu>=0.11
+Requires-Dist: lancedb>=0.15
+Requires-Dist: pyarrow>=15
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn[standard]>=0.29
+Requires-Dist: watchdog>=4.0
+Requires-Dist: tree-sitter>=0.21
+Requires-Dist: tree-sitter-python>=0.23
+Requires-Dist: tree-sitter-javascript>=0.23
+Requires-Dist: tree-sitter-typescript>=0.23
+Requires-Dist: tree-sitter-go>=0.23
+Requires-Dist: tree-sitter-java>=0.23
+Requires-Dist: pypdf>=4.0
+Requires-Dist: pillow>=10.0
+Requires-Dist: cryptography>=42.0
+Requires-Dist: networkx>=3.2
+Requires-Dist: pydantic>=2.6
+Requires-Dist: mcp>=1.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: gitpython>=3.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: neo4j>=5.19
+Requires-Dist: jsonschema>=4.21
+Requires-Dist: python-ulid>=2.2
+Requires-Dist: sse-starlette>=2.0
+Requires-Dist: python-multipart>=0.0.9
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: httpx2>=2.0; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Provides-Extra: ocr
+Requires-Dist: pytesseract>=0.3; extra == "ocr"
+Provides-Extra: server
+Requires-Dist: neo4j>=5.19; extra == "server"
+Dynamic: license-file
+
+# Cortex — Engineering Knowledge Graph
+
+Cortex is a persistent, **workspace-level** knowledge graph for software
+engineering. It models *relationships* (Services, APIs, Decisions, People,
+Documents, ...) rather than files, survives project deletion, and exposes
+that knowledge to any AI model or dev tool over MCP and a REST API.
+
+This repo is a working implementation of the [technical roadmap](.cursor/plans)
+for Cortex, built in Python (Kuzu/LanceDB/SQLite embedded stores, in place
+of the roadmap's suggested Rust core — see "Design notes" below) and
+organized into the roadmap's 7 delivery phases.
+
+## Install
+
+```bash
+# Recommended (isolated global CLI):
+pipx install cortex-kg
+
+# Or with pip:
+pip install cortex-kg
+```
+
+From source (development):
+
+```bash
+git clone https://github.com/RoshanGamage01/Cortex.git
+cd Cortex
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```bash
+# Ingest a project (or the bundled sample repo from a clone):
+cortex --workspace demo ingest examples/sample_repo --project SampleApp
+# Or any local repo:
+# cortex ingest /path/to/your/repo --project MyApp
+
+# Ask questions:
+cortex --workspace demo search "what depends on AuthService"
+cortex --workspace demo context "AuthService" --format markdown
+
+# Explore the graph directly:
+cortex --workspace demo info
+cortex --workspace demo node traverse <node-id> --depth 2
+
+# Serve it to tools:
+cortex --workspace demo serve-api   # REST API on :8420 (see /docs)
+cortex --workspace demo serve-mcp   # MCP server over stdio
+
+# Wire Cursor into a project:
+cortex setup project --write --project MyApp
+```
+
+Data lives at `~/.cortex/<workspace>/` (override with `CORTEX_HOME`) —
+portable, backup-able, and independent of any project's lifecycle.
+
+## User guides
+
+Full setup for Cursor, other platforms, and automation:
+
+| Guide | Description |
+|---|---|
+| [docs/README.md](docs/README.md) | Guide index |
+| [docs/installation.md](docs/installation.md) | pip/pipx install |
+| [docs/cursor.md](docs/cursor.md) | **Cursor MCP + agent instructions** |
+| [docs/project-workflow.md](docs/project-workflow.md) | Ingest and maintain a project |
+| [docs/other-platforms.md](docs/other-platforms.md) | Claude, VS Code, REST, SDKs, CI |
+| [docs/automation.md](docs/automation.md) | Watch mode, hooks, automated rules |
+| [docs/publishing.md](docs/publishing.md) | Release to PyPI |
+
+**Connect Cursor to a project in two commands:**
+
+```bash
+cortex ingest . --project MyApp
+cortex setup project --write --project MyApp   # writes .cursor/mcp.json + agent rule
+```
+
+Reload Cursor after setup.
+
+## Architecture
+
+```
+Sources (code, git, docs, PDFs, images, DB schemas, APIs, notes, plugins)
+   -> Extractors (deterministic first, LLM-assisted where structure is ambiguous)
+   -> Entity Resolver (Candidate -> canonical Node/Edge, with provenance)
+   -> Storage: Kuzu (graph) + LanceDB (vectors) + SQLite FTS5 (keyword) + SQLite (provenance/jobs/ACLs/ontology)
+   -> Hybrid Query Engine (keyword + vector seeds -> graph expansion -> RRF fusion -> re-rank)
+   -> Context Generator (token-budgeted, provenance-carrying context)
+   -> Access layer: MCP server + REST API + TS/Python SDKs
+```
+
+Every node/edge type is **data**, not code: the ontology lives in a schema
+registry (`cortex.ontology.registry`) seeded with the roadmap's default
+taxonomy but extensible at runtime by extractors, plugins, or API/MCP
+clients — no migration required.
+
+## Project layout
+
+```
+src/cortex/
+  config.py              workspace data-dir layout (~/.cortex/<id>/...)
+  models.py               Node / Edge / Candidate / Provenance
+  daemon.py                CortexDaemon: owns every store for one workspace
+  cli.py                    `cortex` command-line entrypoint
+  ontology/                schema registry (ontology-as-data)
+  storage/                 GraphStore (Kuzu), VectorStore (LanceDB), KeywordStore (FTS5), ProvenanceStore
+  ingestion/                content-hashing, entity resolver, the Detect->...->Emit pipeline
+  extractors/               code (tree-sitter), git, db schema, OpenAPI, markdown, PDF, image, notes, LLM-assisted relations
+  sync/                     file watcher, job queue, change feed (pub/sub)
+  retrieval/                embeddings, RRF fusion, graph traversal/impact analysis, query planner, hybrid query engine
+  context/                  token-budgeted context generation for LLMs
+  mcp_server/                MCP server (tools + resources)
+  api/                       REST API (FastAPI)
+  plugins/                   out-of-process plugin interface/loader + example plugin
+  security/                  ACLs, secrets scanning, encryption-at-rest, audit log
+  workspace/                 multi-workspace registry + cross-workspace links + federation
+  versioning/                 bitemporal nodes/edges, supersede/tombstone, history chains
+  server_profile/              Neo4j/Memgraph GraphStore adapter (team-scale server profile)
+  replication/                  CRDT/oplog multi-device sync
+  offline/                       connectivity check + durable cloud-augmentation queue
+  agents/                         agent write-back API + change-feed hooks
+sdk/
+  python/cortex_sdk/         Python REST client SDK
+  typescript/src/index.ts     TypeScript REST client SDK
+examples/sample_repo/          tiny multi-service demo repo used by the tests + quickstart
+scripts/benchmark.py            ingestion/search/context performance benchmark
+tests/                           60+ tests covering every phase below
+```
+
+## Phases (see the plan for full detail)
+
+| Phase | What it delivers | Where |
+|---|---|---|
+| 1. Foundation | Daemon, Kuzu graph store, ontology-as-data, SQLite provenance, minimal API | `daemon.py`, `ontology/`, `storage/` |
+| 2. Extraction & sync | Code/git/schema/API extractors, content-hash incremental sync, resolver v1 | `extractors/`, `ingestion/`, `sync/` |
+| 3. Hybrid retrieval | Vectors, keyword index, traversal, RRF fusion, query planner | `retrieval/` |
+| 4. Access layer | MCP server, REST API, TS+Python SDKs, context generation | `mcp_server/`, `api/`, `sdk/`, `context/` |
+| 5. Unstructured + LLM-assisted | Markdown/PDF/image/notes extractors, schema-constrained LLM relation extraction, feedback loop | `extractors/markdown_extractor.py`, `pdf_extractor.py`, `image_extractor.py`, `notes_extractor.py`, `llm_relation_extractor.py` |
+| 6. Platform | Plugin SDK, ACLs/encryption/secrets-scanning, multi-workspace, bitemporal versioning | `plugins/`, `security/`, `workspace/`, `versioning/` |
+| 7. Scale & agents | Neo4j/Memgraph adapter, CRDT sync, offline fallback, caching, agent write-back | `server_profile/`, `replication/`, `offline/`, `agents/` |
+
+## Design notes / deviations from the roadmap
+
+- **Core engine is Python, not Rust.** The roadmap's storage picks (Kuzu,
+  LanceDB, SQLite) and every architectural boundary (`GraphStore` /
+  `VectorStore` / `Extractor` / plugin protocol) are implemented exactly as
+  specified; only the host language differs, for iteration speed and
+  because Kuzu/LanceDB both ship first-class embedded Python bindings. A
+  Rust rewrite of the core would implement the same `GraphStore` /
+  extraction / retrieval contracts.
+- **Keyword index is SQLite FTS5, not Tantivy.** Zero extra dependency,
+  same "exact-term/symbol search" role in the hybrid retrieval recipe;
+  swappable behind `KeywordStore` if Tantivy bindings are preferred later.
+- **Default embedding model is a deterministic offline hashing embedding**
+  (`cortex.retrieval.embeddings.HashingEmbeddingProvider`), not a trained
+  semantic model — by design, so the whole system (including tests/CI) runs
+  fully offline with no model download. Swap in a real local/cloud model by
+  implementing `EmbeddingProvider`.
+- **LLM-assisted extraction/planning ship transparent local-heuristic
+  defaults** (`cortex.extractors.llm_relation_extractor`,
+  `cortex.retrieval.planner`) rather than calling a cloud model, again for
+  offline-by-default operation; both are written to the exact request/response
+  contract a real LLM backend would fill in via `CORTEX_LLM_PROVIDER`.
+
+## Testing
+
+```bash
+python3 -m pytest tests/ -q
+```
+
+60 tests cover the full pipeline end-to-end (ingest the sample repo through
+every extractor, resolve into the graph, hybrid-search it, generate
+context, serve it over MCP/REST) plus targeted tests per phase (ACLs,
+secrets scanning, encryption, CRDT merge, bitemporal versioning, plugin
+sandboxing, multi-workspace federation, and the performance cache).

cortex_kg-0.1.0/README.md

@@ -0,0 +1,177 @@
+# Cortex — Engineering Knowledge Graph
+
+Cortex is a persistent, **workspace-level** knowledge graph for software
+engineering. It models *relationships* (Services, APIs, Decisions, People,
+Documents, ...) rather than files, survives project deletion, and exposes
+that knowledge to any AI model or dev tool over MCP and a REST API.
+
+This repo is a working implementation of the [technical roadmap](.cursor/plans)
+for Cortex, built in Python (Kuzu/LanceDB/SQLite embedded stores, in place
+of the roadmap's suggested Rust core — see "Design notes" below) and
+organized into the roadmap's 7 delivery phases.
+
+## Install
+
+```bash
+# Recommended (isolated global CLI):
+pipx install cortex-kg
+
+# Or with pip:
+pip install cortex-kg
+```
+
+From source (development):
+
+```bash
+git clone https://github.com/RoshanGamage01/Cortex.git
+cd Cortex
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```bash
+# Ingest a project (or the bundled sample repo from a clone):
+cortex --workspace demo ingest examples/sample_repo --project SampleApp
+# Or any local repo:
+# cortex ingest /path/to/your/repo --project MyApp
+
+# Ask questions:
+cortex --workspace demo search "what depends on AuthService"
+cortex --workspace demo context "AuthService" --format markdown
+
+# Explore the graph directly:
+cortex --workspace demo info
+cortex --workspace demo node traverse <node-id> --depth 2
+
+# Serve it to tools:
+cortex --workspace demo serve-api   # REST API on :8420 (see /docs)
+cortex --workspace demo serve-mcp   # MCP server over stdio
+
+# Wire Cursor into a project:
+cortex setup project --write --project MyApp
+```
+
+Data lives at `~/.cortex/<workspace>/` (override with `CORTEX_HOME`) —
+portable, backup-able, and independent of any project's lifecycle.
+
+## User guides
+
+Full setup for Cursor, other platforms, and automation:
+
+| Guide | Description |
+|---|---|
+| [docs/README.md](docs/README.md) | Guide index |
+| [docs/installation.md](docs/installation.md) | pip/pipx install |
+| [docs/cursor.md](docs/cursor.md) | **Cursor MCP + agent instructions** |
+| [docs/project-workflow.md](docs/project-workflow.md) | Ingest and maintain a project |
+| [docs/other-platforms.md](docs/other-platforms.md) | Claude, VS Code, REST, SDKs, CI |
+| [docs/automation.md](docs/automation.md) | Watch mode, hooks, automated rules |
+| [docs/publishing.md](docs/publishing.md) | Release to PyPI |
+
+**Connect Cursor to a project in two commands:**
+
+```bash
+cortex ingest . --project MyApp
+cortex setup project --write --project MyApp   # writes .cursor/mcp.json + agent rule
+```
+
+Reload Cursor after setup.
+
+## Architecture
+
+```
+Sources (code, git, docs, PDFs, images, DB schemas, APIs, notes, plugins)
+   -> Extractors (deterministic first, LLM-assisted where structure is ambiguous)
+   -> Entity Resolver (Candidate -> canonical Node/Edge, with provenance)
+   -> Storage: Kuzu (graph) + LanceDB (vectors) + SQLite FTS5 (keyword) + SQLite (provenance/jobs/ACLs/ontology)
+   -> Hybrid Query Engine (keyword + vector seeds -> graph expansion -> RRF fusion -> re-rank)
+   -> Context Generator (token-budgeted, provenance-carrying context)
+   -> Access layer: MCP server + REST API + TS/Python SDKs
+```
+
+Every node/edge type is **data**, not code: the ontology lives in a schema
+registry (`cortex.ontology.registry`) seeded with the roadmap's default
+taxonomy but extensible at runtime by extractors, plugins, or API/MCP
+clients — no migration required.
+
+## Project layout
+
+```
+src/cortex/
+  config.py              workspace data-dir layout (~/.cortex/<id>/...)
+  models.py               Node / Edge / Candidate / Provenance
+  daemon.py                CortexDaemon: owns every store for one workspace
+  cli.py                    `cortex` command-line entrypoint
+  ontology/                schema registry (ontology-as-data)
+  storage/                 GraphStore (Kuzu), VectorStore (LanceDB), KeywordStore (FTS5), ProvenanceStore
+  ingestion/                content-hashing, entity resolver, the Detect->...->Emit pipeline
+  extractors/               code (tree-sitter), git, db schema, OpenAPI, markdown, PDF, image, notes, LLM-assisted relations
+  sync/                     file watcher, job queue, change feed (pub/sub)
+  retrieval/                embeddings, RRF fusion, graph traversal/impact analysis, query planner, hybrid query engine
+  context/                  token-budgeted context generation for LLMs
+  mcp_server/                MCP server (tools + resources)
+  api/                       REST API (FastAPI)
+  plugins/                   out-of-process plugin interface/loader + example plugin
+  security/                  ACLs, secrets scanning, encryption-at-rest, audit log
+  workspace/                 multi-workspace registry + cross-workspace links + federation
+  versioning/                 bitemporal nodes/edges, supersede/tombstone, history chains
+  server_profile/              Neo4j/Memgraph GraphStore adapter (team-scale server profile)
+  replication/                  CRDT/oplog multi-device sync
+  offline/                       connectivity check + durable cloud-augmentation queue
+  agents/                         agent write-back API + change-feed hooks
+sdk/
+  python/cortex_sdk/         Python REST client SDK
+  typescript/src/index.ts     TypeScript REST client SDK
+examples/sample_repo/          tiny multi-service demo repo used by the tests + quickstart
+scripts/benchmark.py            ingestion/search/context performance benchmark
+tests/                           60+ tests covering every phase below
+```
+
+## Phases (see the plan for full detail)
+
+| Phase | What it delivers | Where |
+|---|---|---|
+| 1. Foundation | Daemon, Kuzu graph store, ontology-as-data, SQLite provenance, minimal API | `daemon.py`, `ontology/`, `storage/` |
+| 2. Extraction & sync | Code/git/schema/API extractors, content-hash incremental sync, resolver v1 | `extractors/`, `ingestion/`, `sync/` |
+| 3. Hybrid retrieval | Vectors, keyword index, traversal, RRF fusion, query planner | `retrieval/` |
+| 4. Access layer | MCP server, REST API, TS+Python SDKs, context generation | `mcp_server/`, `api/`, `sdk/`, `context/` |
+| 5. Unstructured + LLM-assisted | Markdown/PDF/image/notes extractors, schema-constrained LLM relation extraction, feedback loop | `extractors/markdown_extractor.py`, `pdf_extractor.py`, `image_extractor.py`, `notes_extractor.py`, `llm_relation_extractor.py` |
+| 6. Platform | Plugin SDK, ACLs/encryption/secrets-scanning, multi-workspace, bitemporal versioning | `plugins/`, `security/`, `workspace/`, `versioning/` |
+| 7. Scale & agents | Neo4j/Memgraph adapter, CRDT sync, offline fallback, caching, agent write-back | `server_profile/`, `replication/`, `offline/`, `agents/` |
+
+## Design notes / deviations from the roadmap
+
+- **Core engine is Python, not Rust.** The roadmap's storage picks (Kuzu,
+  LanceDB, SQLite) and every architectural boundary (`GraphStore` /
+  `VectorStore` / `Extractor` / plugin protocol) are implemented exactly as
+  specified; only the host language differs, for iteration speed and
+  because Kuzu/LanceDB both ship first-class embedded Python bindings. A
+  Rust rewrite of the core would implement the same `GraphStore` /
+  extraction / retrieval contracts.
+- **Keyword index is SQLite FTS5, not Tantivy.** Zero extra dependency,
+  same "exact-term/symbol search" role in the hybrid retrieval recipe;
+  swappable behind `KeywordStore` if Tantivy bindings are preferred later.
+- **Default embedding model is a deterministic offline hashing embedding**
+  (`cortex.retrieval.embeddings.HashingEmbeddingProvider`), not a trained
+  semantic model — by design, so the whole system (including tests/CI) runs
+  fully offline with no model download. Swap in a real local/cloud model by
+  implementing `EmbeddingProvider`.
+- **LLM-assisted extraction/planning ship transparent local-heuristic
+  defaults** (`cortex.extractors.llm_relation_extractor`,
+  `cortex.retrieval.planner`) rather than calling a cloud model, again for
+  offline-by-default operation; both are written to the exact request/response
+  contract a real LLM backend would fill in via `CORTEX_LLM_PROVIDER`.
+
+## Testing
+
+```bash
+python3 -m pytest tests/ -q
+```
+
+60 tests cover the full pipeline end-to-end (ingest the sample repo through
+every extractor, resolve into the graph, hybrid-search it, generate
+context, serve it over MCP/REST) plus targeted tests per phase (ACLs,
+secrets scanning, encryption, CRDT merge, bitemporal versioning, plugin
+sandboxing, multi-workspace federation, and the performance cache).

cortex_kg-0.1.0/docs/README.md

@@ -0,0 +1,23 @@
+# Cortex user guides
+
+Step-by-step guides for installing Cortex and connecting it to your tools.
+
+| Guide | What it covers |
+|---|---|
+| [Installation](installation.md) | pip/pipx install, first run, workspaces |
+| [Cursor integration](cursor.md) | MCP setup, per-project config, agent instructions |
+| [Project workflow](project-workflow.md) | Ingest a repo, keep knowledge fresh, multi-project |
+| [Other platforms](other-platforms.md) | Claude Desktop, VS Code, REST API, SDKs, CI |
+| [Automation](automation.md) | Watch mode, cron, Git hooks, agent write-back |
+| [Publishing](publishing.md) | Release `cortex-kg` to PyPI |
+
+**Quick one-liner for a new project:**
+
+```bash
+pipx install cortex-kg          # or: pip install -e . from this repo
+cortex init
+cortex ingest . --project MyApp
+cortex setup project --write --project MyApp
+```
+
+Then reload Cursor — the AI can call Cortex MCP tools in that project.

cortex_kg-0.1.0/docs/automation.md

@@ -0,0 +1,164 @@
+# Automation
+
+Ways to keep Cortex updated and instruct AI agents automatically.
+
+---
+
+## 1. Watch mode (local dev)
+
+Re-ingest files as they change:
+
+```bash
+cortex watch /path/to/repo --project MyApp
+```
+
+Runs until Ctrl+C. Uses filesystem events with ~750ms debounce.
+
+**Tip:** Run in a dedicated terminal tab or tmux pane while coding.
+
+---
+
+## 2. Project bootstrap script
+
+Add `scripts/cortex-sync.sh` to your repo:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+PROJECT_NAME="${CORTEX_PROJECT:-$(basename "$PWD")}"
+WORKSPACE="${CORTEX_WORKSPACE:-default}"
+cortex --workspace "$WORKSPACE" ingest . --project "$PROJECT_NAME"
+```
+
+```bash
+chmod +x scripts/cortex-sync.sh
+./scripts/cortex-sync.sh
+```
+
+---
+
+## 3. Git post-merge hook
+
+Re-index after pulling main:
+
+`.git/hooks/post-merge`:
+
+```bash
+#!/bin/sh
+cortex --workspace default ingest . --project MyApp 2>/dev/null || true
+```
+
+---
+
+## 4. Cron (nightly refresh)
+
+```cron
+0 2 * * * cd /home/you/projects/my-app && /usr/local/bin/cortex --workspace default ingest . --project MyApp >> ~/.cortex/ingest.log 2>&1
+```
+
+---
+
+## 5. Cursor agent rules (automated instructions)
+
+`cortex setup project --write` installs `.cursor/rules/cortex.mdc`.
+
+This tells the AI to:
+
+| Trigger | Automated behavior |
+|---|---|
+| Refactor / delete / rename service | Call `explain_impact` first |
+| Architecture or “how does X work?” questions | Call `search_knowledge` + `get_context` |
+| User states a decision | Call `add_note` + `link` |
+| Low-confidence graph edge shown | Ask user; use `confirm_edge` or `reject_edge` |
+| No graph data for topic | Suggest `cortex ingest . --project …` |
+
+Customize the rule for your team — template at `docs/templates/cortex-agent-rule.mdc`.
+
+---
+
+## 6. MCP server instructions (built-in)
+
+The MCP server ships with system instructions (see `mcp_server/server.py`):
+
+> Cortex models relationships between engineering concepts, not files.
+> Use search_knowledge, get_context, and explain_impact before changes.
+
+Cursor merges these with your project rules.
+
+---
+
+## 7. Change feed (event-driven)
+
+When the REST API is running:
+
+```bash
+curl -N "http://localhost:8420/change-feed/stream?workspace=default"
+```
+
+Events include `node_added`, `edge_added`, ingest completions, and agent writebacks.
+
+Use for:
+
+- Slack notifications when ADRs are added
+- Triggering downstream doc generation
+- Agent hooks (`cortex.agents.hooks`)
+
+---
+
+## 8. Background job queue
+
+Ingest enqueues embedding jobs automatically. Process them:
+
+```python
+from cortex.daemon import get_daemon
+from cortex.sync.job_queue import JobWorker
+
+daemon = get_daemon("default")
+worker = JobWorker(daemon)
+worker.run_once()  # or run in a loop / thread
+```
+
+---
+
+## 9. Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `CORTEX_HOME` | Override `~/.cortex` data root |
+| `CORTEX_LLM_PROVIDER` | Plug in cloud/local LLM for relation extraction (future) |
+| `CORTEX_PROJECT_ROOT` | Set by project MCP config; optional hint for tools |
+
+---
+
+## 10. Recommended automation stack
+
+**Solo developer:**
+
+1. `cortex ingest .` once
+2. `cortex setup project --write`
+3. `cortex watch .` in background while coding
+
+**Team:**
+
+1. Commit `.cursor/mcp.json` + `.cursor/rules/cortex.mdc`
+2. Document `cortex ingest` in README
+3. Optional CI ingest on `main`
+4. Optional shared REST server for dashboards
+
+---
+
+## Setup command reference
+
+```bash
+# Print MCP JSON for Cursor
+cortex setup cursor --workspace default
+
+# Write .cursor/mcp.json + agent rule
+cortex setup project --write --project MyApp
+
+# Claude Desktop config
+cortex setup claude --write
+
+# VS Code (same JSON as Cursor)
+cortex setup vscode --write --path .
+```