code-atlas-mcp 0.2.0.dev1__tar.gz → 0.3.1__tar.gz

code_atlas_mcp-0.3.1/.gitattributes

@@ -0,0 +1,84 @@
+# Default
+# ==================
+*                   text=auto eol=lf
+
+# Python Source files
+# =================
+*.pxd               text diff=python
+*.py                text diff=python
+*.py3               text diff=python
+*.pyw               text diff=python
+*.pyx               text diff=python
+*.pyz               text diff=python
+*.pyi               text diff=python
+
+# Python Binary files
+# =================
+*.db                binary
+*.p                 binary
+*.pkl               binary
+*.pickle            binary
+*.pyc               binary export-ignore
+*.pyo               binary export-ignore
+*.pyd               binary
+
+# Jupyter notebook
+# =================
+*.ipynb             text
+
+# ML models
+# =================
+*.h5                filter=lfs diff=lfs merge=lfs -text
+*.onnx              filter=lfs diff=lfs merge=lfs -text
+*.model             filter=lfs diff=lfs merge=lfs -text
+*.msgpack           filter=lfs diff=lfs merge=lfs -text
+*.pb                filter=lfs diff=lfs merge=lfs -text
+*.pt                filter=lfs diff=lfs merge=lfs -text
+*.pth               filter=lfs diff=lfs merge=lfs -text
+pytorch_model.bin   filter=lfs diff=lfs merge=lfs -text
+tokenizer.json      filter=lfs diff=lfs merge=lfs -text
+unigram.json        filter=lfs diff=lfs merge=lfs -text
+
+# Data files
+# =================
+*.csv               filter=lfs diff=lfs merge=lfs -text
+*.tsv               filter=lfs diff=lfs merge=lfs -text
+*.parquet           filter=lfs diff=lfs merge=lfs
+
+# Presentation files
+# =================
+*.pptx              filter=lfs diff=lfs merge=lfs -text
+*.word              filter=lfs diff=lfs merge=lfs -text
+*.xlsx              filter=lfs diff=lfs merge=lfs -text
+*.xls               filter=lfs diff=lfs merge=lfs -text
+*.pdf               filter=lfs diff=lfs merge=lfs -text
+
+# Archives
+# =================
+*.7z                filter=lfs diff=lfs merge=lfs -text
+*.br                filter=lfs diff=lfs merge=lfs -text
+*.gz                filter=lfs diff=lfs merge=lfs -text
+*.tar               filter=lfs diff=lfs merge=lfs -text
+*.tgz               filter=lfs diff=lfs merge=lfs -text
+*.tar.gz            filter=lfs diff=lfs merge=lfs -text
+*.zip               filter=lfs diff=lfs merge=lfs -text
+*.rar               filter=lfs diff=lfs merge=lfs -text
+
+# Image files
+# =================
+*.jpg           filter=lfs diff=lfs merge=lfs -text
+*.jpeg          filter=lfs diff=lfs merge=lfs -text
+*.png           filter=lfs diff=lfs merge=lfs -text
+*.gif           filter=lfs diff=lfs merge=lfs -text
+*.webp          filter=lfs diff=lfs merge=lfs -text
+*.bmp           filter=lfs diff=lfs merge=lfs -text
+*.svg           filter=lfs diff=lfs merge=lfs -text
+*.tiff          filter=lfs diff=lfs merge=lfs -text
+
+# Other
+# =================
+# Windows - keep CRLF
+*.exe           filter=lfs diff=lfs merge=lfs -text
+*.bat            text eol=crlf
+*.cmd            text eol=crlf
+*.ps1            text eol=crlf

{code_atlas_mcp-0.2.0.dev1 → code_atlas_mcp-0.3.1}/.github/workflows/release.yml

@@ -31,19 +31,22 @@ jobs:
       contents: write
 
     steps:
+      - uses: actions/create-github-app-token@v1
+        id: app-token
+        with:
+          app-id: ${{ vars.RELEASE_APP_ID }}
+          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+
       - uses: actions/checkout@v6
         with:
           fetch-depth: 0
-          ref: ${{ github.ref_name }}
-
-      - name: Pin to triggering SHA
-        run: git reset --hard ${{ github.sha }}
+          token: ${{ steps.app-token.outputs.token }}
 
       - name: Semantic Release
         id: release
         uses: python-semantic-release/python-semantic-release@v10
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
+          github_token: ${{ steps.app-token.outputs.token }}
           git_committer_name: "github-actions[bot]"
           git_committer_email: "github-actions[bot]@users.noreply.github.com"
           force: ${{ inputs.force || '' }}
@@ -53,7 +56,7 @@ jobs:
         if: steps.release.outputs.released == 'true'
         uses: python-semantic-release/publish-action@v10
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
+          github_token: ${{ steps.app-token.outputs.token }}
           tag: ${{ steps.release.outputs.tag }}
 
     outputs:
@@ -67,7 +70,7 @@ jobs:
   # ------------------------------------------------------------------- #
   publish-pypi:
     needs: release
-    if: needs.release.outputs.released == 'true'
+    if: needs.release.outputs.released == 'true' && needs.release.outputs.is_prerelease != 'true'
     runs-on: ubuntu-latest
     environment:
       name: pypi
@@ -89,6 +92,15 @@ jobs:
         with:
           python-version: "3.14-dev"
 
+      - name: Verify version matches tag
+        run: |
+          TAG="${{ needs.release.outputs.tag }}"
+          TOML_VERSION=$(python -c "import tomllib; print('v' + tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$TAG" != "$TOML_VERSION" ]; then
+            echo "::error::Tag $TAG does not match pyproject.toml version $TOML_VERSION"
+            exit 1
+          fi
+
       - run: uv build
 
       - uses: pypa/gh-action-pypi-publish@release/v1

{code_atlas_mcp-0.2.0.dev1 → code_atlas_mcp-0.3.1}/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 <!-- version list -->
 
+## v0.3.1 (2026-03-07)
+
+### Bug Fixes
+
+- **ci**: Use GitHub App token to push to protected main branch
+  ([`13b46b9`](https://github.com/SerPeter/code-atlas/commit/13b46b972f900e4d1170b9c42af0c40d9c0cf35c))
+
+
+## v0.3.0 (2026-03-04)
+
+### Features
+
+- **indexing**: Add file hash gate to skip unchanged files
+  ([#9](https://github.com/SerPeter/code-atlas/pull/9))
+- **indexing**: Add per-file cooldown for daemon mode
+  ([#9](https://github.com/SerPeter/code-atlas/pull/9))
+
+### Performance Improvements
+
+- Reduce RTTs across indexing and query pipelines
+  ([`cf3a519`](https://github.com/SerPeter/code-atlas/commit/cf3a519))
+
+### Refactoring
+
+- **indexing**: Eliminate Tier 1 consumer, simplify to two-tier pipeline
+  ([#9](https://github.com/SerPeter/code-atlas/pull/9))
+- **indexing**: Rename Tier 2/3 to AST/Embed stage across code and docs
+  ([#9](https://github.com/SerPeter/code-atlas/pull/9))
+
+### Bug Fixes
+
+- **ci**: Remove detached HEAD checkout in release workflow
+
+## v0.2.0-dev.2 (2026-02-23)
+
+### Bug Fixes
+
+- **indexing**: Label-constrained queries, PEL reclaim, and drain progress
+  ([`9ec9150`](https://github.com/SerPeter/code-atlas/commit/9ec915088058b05396a506ca23bfd0a0492d67f6))
+
+
 ## v0.2.0-dev.1 (2026-02-23)
 
 ### Bug Fixes
@@ -13,14 +54,15 @@
 - **ci**: Resolve ty check failures with --all-extras in CI
   ([`3f74816`](https://github.com/SerPeter/code-atlas/commit/3f7481635091d2d676aed75c3fbcaa5db4332242))
 
-- **consumers**: Group batches by project in Tier1/Tier2
+- **consumers**: Group batches by project in AST/Embed consumers
   ([#2](https://github.com/SerPeter/code-atlas/pull/2),
   [`5107b24`](https://github.com/SerPeter/code-atlas/commit/5107b24a7dfbcb44cadc7917f632ae6a9743c057))
 
 ### Build System
 
 - **release**: Add python-semantic-release v10 for automated releases
-  ([`044e9a3`](https://github.com/SerPeter/code-atlas/commit/044e9a31c5f7673a4be45a6519860d247e1b3cb1))
+  ([#5](https://github.com/SerPeter/code-atlas/pull/5),
+  [`de9c06d`](https://github.com/SerPeter/code-atlas/commit/de9c06d8c1e1744a92ff7ef160e06f859b5aa768))
 
 ### Features
 
@@ -181,7 +223,7 @@
 - **docs**: Add markdown parser with tree-sitter-markdown
   ([`e8d372c`](https://github.com/SerPeter/code-atlas/commit/e8d372c162652d6d73d1f66da5e14a61fcb2136a))
 
-- **embeddings**: Add EmbedClient with litellm routing and Tier 3 pipeline
+- **embeddings**: Add EmbedClient with litellm routing and embed pipeline
   ([`ad7c972`](https://github.com/SerPeter/code-atlas/commit/ad7c9726f2e48fdb8746b50547089c5c483bcb75))
 
 - **embeddings**: Add three-tier embedding cache with Valkey backend
@@ -232,7 +274,7 @@
 - **naming**: Worktree-aware naming and monorepo sub-project prefixing
   ([`2acdfb3`](https://github.com/SerPeter/code-atlas/commit/2acdfb33ba4b486f966272a01cf8a37f670661f6))
 
-- **parser**: Add py-tree-sitter parser, implement Tier 2 pipeline, drop Rust
+- **parser**: Add py-tree-sitter parser, implement AST pipeline, drop Rust
   ([`d56e7d2`](https://github.com/SerPeter/code-atlas/commit/d56e7d2a686ec279a52d85bbc4903f4d85f51a4e))
 
 - **parsing**: Add multi-language support (10 languages, 7 modules)

{code_atlas_mcp-0.2.0.dev1 → code_atlas_mcp-0.3.1}/CLAUDE.md

@@ -51,7 +51,7 @@ src/code_atlas/
 ├── __init__.py          # __version__ only
 ├── schema.py            # Graph schema (labels, relationships, DDL generators)
 ├── settings.py          # Pydantic configuration (atlas.toml + env vars)
-├── events.py            # Event types (FileChanged, ASTDirty, EmbedDirty) + Valkey Streams EventBus
+├── events.py            # Event types (FileChanged, EmbedDirty) + Valkey Streams EventBus
 ├── telemetry.py         # OpenTelemetry integration
 ├── cli.py               # Typer CLI entrypoint (index, search, status, mcp, daemon commands)
 │
@@ -69,7 +69,7 @@ src/code_atlas/
 │
 ├── indexing/
 │   ├── orchestrator.py  # Full-index, monorepo detection, staleness checking
-│   ├── consumers.py     # Tier 1/2/3 event consumers (batch-pull pattern)
+│   ├── consumers.py     # AST + Embed event consumers (batch-pull pattern)
 │   ├── watcher.py       # Filesystem watcher (watchfiles + hybrid debounce)
 │   └── daemon.py        # Daemon lifecycle manager (watcher + pipeline)
 │
@@ -78,12 +78,14 @@ src/code_atlas/
     └── health.py        # Infrastructure health checks + diagnostics
 ```
 
-**Event Pipeline:** File Watcher → Valkey Streams → Tier 1 (graph metadata) → Tier 2 (AST diff + gate) → Tier 3 (embeddings) → Memgraph
+**Event Pipeline:** File Watcher → Valkey Streams → AST stage (hash gate + parse + diff) → Embed stage (embeddings) → Memgraph
 
 **Query Pipeline:** MCP Server → Query Router → [Graph Search | Vector Search | BM25 Search] → RRF Fusion → Results
 
 **Deployment:** Daemon (`atlas daemon start`) for indexing + MCP (`atlas mcp`) per agent session, decoupled via Valkey + Memgraph
 
+**Event model:** Events are atomic — one logical change per event (one file per FileChanged, one entity per EmbedDirty). Never bundle lists of work items into a single event; use `EventBus.publish_many()` for network-efficient batch publishing. The consumer's `max_batch_size` must directly control work volume, not just message count.
+
 **Infrastructure:** Memgraph (graph DB, port 7687), TEI (embeddings, port 8080), Valkey (event bus, port 6379)
 
 ## Code Style

{code_atlas_mcp-0.2.0.dev1 → code_atlas_mcp-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-atlas-mcp
-Version: 0.2.0.dev1
+Version: 0.3.1
 Summary: A code intelligence graph that gives AI coding agents deep, token-efficient understanding of your codebase.
 Project-URL: Homepage, https://github.com/SerPeter/code-atlas
 Project-URL: Documentation, https://github.com/SerPeter/code-atlas/tree/main/docs
@@ -27,11 +27,13 @@ Requires-Dist: loguru~=0.7
 Requires-Dist: mcp~=1.26
 Requires-Dist: neo4j~=6.1
 Requires-Dist: numpy~=2.4
+Requires-Dist: orjson>=3.10
 Requires-Dist: pathspec~=1.0
 Requires-Dist: pydantic-settings~=2.12
 Requires-Dist: pydantic~=2.12
 Requires-Dist: python-dotenv~=1.1
 Requires-Dist: redis[hiredis]~=7.1
+Requires-Dist: tenacity~=9.1
 Requires-Dist: tiktoken~=0.12
 Requires-Dist: tree-sitter-markdown~=0.5
 Requires-Dist: tree-sitter-python~=0.23
@@ -130,30 +132,30 @@ For a detailed comparison covering DeepWiki, Cursor, Sourcegraph Cody, Kit, code
 
 15 tools exposed via the [Model Context Protocol](https://modelcontextprotocol.io/), designed to minimize context window overhead.
 
-| Tool                   | What it does                                                                                 | Search | Full |
-| ---------------------- | -------------------------------------------------------------------------------------------- | -----: | ---: |
-| **Search**             |                                                                                              |        |      |
-| `hybrid_search`        | **Primary tool** — fuses graph + BM25 + vector via RRF. Auto-adjusts weights by query shape. |   ~117 | ~497 |
-| `text_search`          | BM25 keyword search. Quoted phrases, wildcards, field-specific queries.                      |    ~90 | ~275 |
-| `vector_search`        | Semantic similarity via embeddings. Finds code by meaning, not name.                         |    ~67 | ~297 |
-| `get_node`             | Find entities by name. Cascade: exact uid → name → suffix → prefix → contains.               |   ~100 | ~254 |
-| **Navigation**         |                                                                                              |        |      |
-| `get_context`          | Expand a node's neighborhood: parent, siblings, callers, callees, docs.                      |    ~64 | ~273 |
-| `cypher_query`         | Run read-only Cypher against the graph. Auto-limited, write-protected.                       |    ~59 | ~168 |
-| **Analysis**           |                                                                                              |        |      |
-| `analyze_repo`         | Structure, centrality, dependencies, or pattern analysis.                                    |    ~41 | ~266 |
-| `generate_diagram`     | Mermaid diagrams: packages, imports, inheritance, module detail.                             |    ~37 | ~254 |
-| **Guidance**           |                                                                                              |        |      |
-| `get_usage_guide`      | Quick-start or topic-specific guidance for the agent.                                        |    ~35 | ~106 |
-| `plan_search_strategy` | Recommends which search tool + params for a question.                                        |    ~40 |  ~97 |
-| `validate_cypher`      | Catches Cypher errors before execution.                                                      |    ~58 | ~116 |
-| `schema_info`          | Full graph schema: labels, relationships, Cypher examples.                                   |    ~75 |  ~96 |
-| **Status**             |                                                                                              |        |      |
-| `index_status`         | Projects, entity counts, schema version, index health.                                       |    ~72 |  ~93 |
-| `list_projects`        | Monorepo project list with dependency relationships.                                         |    ~56 |  ~77 |
-| `health_check`         | Infrastructure diagnostics: Memgraph, TEI, Valkey, schema.                                   |    ~55 |  ~76 |
-
-Token counts measured from MCP JSON tool definitions (tiktoken cl100k_base). **Search** = name + description (~966 total); **Full** = name + description + parameter schema with field descriptions, enums, and constraints (~2,945 total). All parameters are self-documented — agents can one-shot any tool without calling `get_usage_guide` first.
+| Tool                   | What it does                                                                                 | Search | Full | Latency (avg / p95) |
+| ---------------------- | -------------------------------------------------------------------------------------------- | -----: | ---: | ------------------: |
+| **Search**             |                                                                                              |        |      |                     |
+| `hybrid_search`        | **Primary tool** — fuses graph + BM25 + vector via RRF. Auto-adjusts weights by query shape. |   ~117 | ~497 |        548 / 677 ms |
+| `text_search`          | BM25 keyword search. Quoted phrases, wildcards, field-specific queries.                      |    ~90 | ~275 |          34 / 36 ms |
+| `vector_search`        | Semantic similarity via embeddings. Finds code by meaning, not name.                         |    ~67 | ~297 |        102 / 125 ms |
+| `get_node`             | Find entities by name. Cascade: exact (uid + name) → partial (suffix > prefix > contains).   |   ~100 | ~254 |            7 / 8 ms |
+| **Navigation**         |                                                                                              |        |      |                     |
+| `get_context`          | Expand a node's neighborhood: parent, siblings, callers, callees, docs.                      |    ~64 | ~273 |          34 / 36 ms |
+| `cypher_query`         | Run read-only Cypher against the graph. Auto-limited, write-protected.                       |    ~59 | ~168 |            3 / 3 ms |
+| **Analysis**           |                                                                                              |        |      |                     |
+| `analyze_repo`         | Structure, centrality, dependencies, pattern, or quality analysis.                           |    ~41 | ~266 |          22 / 23 ms |
+| `generate_diagram`     | Mermaid diagrams: packages, imports, inheritance, module detail.                             |    ~37 | ~254 |            3 / 3 ms |
+| **Guidance**           |                                                                                              |        |      |                     |
+| `get_usage_guide`      | Quick-start or topic-specific guidance for the agent.                                        |    ~35 | ~106 |        < 1 / < 1 ms |
+| `plan_search_strategy` | Recommends which search tool + params for a question.                                        |    ~40 |  ~97 |        < 1 / < 1 ms |
+| `validate_cypher`      | Catches Cypher errors before execution.                                                      |    ~58 | ~116 |            1 / 2 ms |
+| `schema_info`          | Full graph schema: labels, relationships, Cypher examples.                                   |    ~75 |  ~96 |        < 1 / < 1 ms |
+| **Status**             |                                                                                              |        |      |                     |
+| `index_status`         | Projects, entity counts, schema version, index health.                                       |    ~72 |  ~93 |          22 / 23 ms |
+| `list_projects`        | Monorepo project list with dependency relationships.                                         |    ~56 |  ~77 |          12 / 13 ms |
+| `health_check`         | Infrastructure diagnostics: Memgraph, TEI, Valkey, schema.                                   |    ~55 |  ~76 |        218 / 264 ms |
+
+Token counts measured from MCP JSON tool definitions (tiktoken cl100k_base). **Search** = name + description (~966 total); **Full** = name + description + parameter schema with field descriptions, enums, and constraints (~2,945 total). All parameters are self-documented — agents can one-shot any tool without calling `get_usage_guide` first. **Latency** measured with local TEI embeddings on the code-atlas repo (~1,400 entities), 5 iterations, warm embedding cache. See `scripts/profile_query.py`.
 
 ## Quick Start
 
@@ -220,15 +222,15 @@ uv run pre-commit install
 
 ## Performance
 
-| Metric              | Value                 |
-| ------------------- | --------------------- |
-| Parse throughput    | **600–700 files/sec** |
-| Graph search (p50)  | 8 ms                  |
-| BM25 search (p50)   | 10 ms                 |
-| Vector search (p50) | 47 ms                 |
-| Concurrent QPS      | **238** (zero errors) |
+| Metric                     | Value                 |
+| -------------------------- | --------------------- |
+| Full index (107 files)     | **55s** (local TEI)   |
+| Parse-only throughput      | **600–700 files/sec** |
+| `get_node` / `text_search` | 7 ms / 34 ms          |
+| `vector_search`            | 102 ms                |
+| Concurrent QPS             | **238** (zero errors) |
 
-Full benchmark tables and methodology: [docs/benchmarks.md](docs/benchmarks.md)
+Full index includes parsing, graph upserts, and embedding via local TEI (8 concurrent workers). Parse-only is raw tree-sitter CPU time without I/O. Query latencies are averages from `scripts/profile_query.py`. Full benchmark tables: [docs/benchmarks.md](docs/benchmarks.md)
 
 ## Documentation
 

{code_atlas_mcp-0.2.0.dev1 → code_atlas_mcp-0.3.1}/README.md

@@ -54,30 +54,30 @@ For a detailed comparison covering DeepWiki, Cursor, Sourcegraph Cody, Kit, code
 
 15 tools exposed via the [Model Context Protocol](https://modelcontextprotocol.io/), designed to minimize context window overhead.
 
-| Tool                   | What it does                                                                                 | Search | Full |
-| ---------------------- | -------------------------------------------------------------------------------------------- | -----: | ---: |
-| **Search**             |                                                                                              |        |      |
-| `hybrid_search`        | **Primary tool** — fuses graph + BM25 + vector via RRF. Auto-adjusts weights by query shape. |   ~117 | ~497 |
-| `text_search`          | BM25 keyword search. Quoted phrases, wildcards, field-specific queries.                      |    ~90 | ~275 |
-| `vector_search`        | Semantic similarity via embeddings. Finds code by meaning, not name.                         |    ~67 | ~297 |
-| `get_node`             | Find entities by name. Cascade: exact uid → name → suffix → prefix → contains.               |   ~100 | ~254 |
-| **Navigation**         |                                                                                              |        |      |
-| `get_context`          | Expand a node's neighborhood: parent, siblings, callers, callees, docs.                      |    ~64 | ~273 |
-| `cypher_query`         | Run read-only Cypher against the graph. Auto-limited, write-protected.                       |    ~59 | ~168 |
-| **Analysis**           |                                                                                              |        |      |
-| `analyze_repo`         | Structure, centrality, dependencies, or pattern analysis.                                    |    ~41 | ~266 |
-| `generate_diagram`     | Mermaid diagrams: packages, imports, inheritance, module detail.                             |    ~37 | ~254 |
-| **Guidance**           |                                                                                              |        |      |
-| `get_usage_guide`      | Quick-start or topic-specific guidance for the agent.                                        |    ~35 | ~106 |
-| `plan_search_strategy` | Recommends which search tool + params for a question.                                        |    ~40 |  ~97 |
-| `validate_cypher`      | Catches Cypher errors before execution.                                                      |    ~58 | ~116 |
-| `schema_info`          | Full graph schema: labels, relationships, Cypher examples.                                   |    ~75 |  ~96 |
-| **Status**             |                                                                                              |        |      |
-| `index_status`         | Projects, entity counts, schema version, index health.                                       |    ~72 |  ~93 |
-| `list_projects`        | Monorepo project list with dependency relationships.                                         |    ~56 |  ~77 |
-| `health_check`         | Infrastructure diagnostics: Memgraph, TEI, Valkey, schema.                                   |    ~55 |  ~76 |
-
-Token counts measured from MCP JSON tool definitions (tiktoken cl100k_base). **Search** = name + description (~966 total); **Full** = name + description + parameter schema with field descriptions, enums, and constraints (~2,945 total). All parameters are self-documented — agents can one-shot any tool without calling `get_usage_guide` first.
+| Tool                   | What it does                                                                                 | Search | Full | Latency (avg / p95) |
+| ---------------------- | -------------------------------------------------------------------------------------------- | -----: | ---: | ------------------: |
+| **Search**             |                                                                                              |        |      |                     |
+| `hybrid_search`        | **Primary tool** — fuses graph + BM25 + vector via RRF. Auto-adjusts weights by query shape. |   ~117 | ~497 |        548 / 677 ms |
+| `text_search`          | BM25 keyword search. Quoted phrases, wildcards, field-specific queries.                      |    ~90 | ~275 |          34 / 36 ms |
+| `vector_search`        | Semantic similarity via embeddings. Finds code by meaning, not name.                         |    ~67 | ~297 |        102 / 125 ms |
+| `get_node`             | Find entities by name. Cascade: exact (uid + name) → partial (suffix > prefix > contains).   |   ~100 | ~254 |            7 / 8 ms |
+| **Navigation**         |                                                                                              |        |      |                     |
+| `get_context`          | Expand a node's neighborhood: parent, siblings, callers, callees, docs.                      |    ~64 | ~273 |          34 / 36 ms |
+| `cypher_query`         | Run read-only Cypher against the graph. Auto-limited, write-protected.                       |    ~59 | ~168 |            3 / 3 ms |
+| **Analysis**           |                                                                                              |        |      |                     |
+| `analyze_repo`         | Structure, centrality, dependencies, pattern, or quality analysis.                           |    ~41 | ~266 |          22 / 23 ms |
+| `generate_diagram`     | Mermaid diagrams: packages, imports, inheritance, module detail.                             |    ~37 | ~254 |            3 / 3 ms |
+| **Guidance**           |                                                                                              |        |      |                     |
+| `get_usage_guide`      | Quick-start or topic-specific guidance for the agent.                                        |    ~35 | ~106 |        < 1 / < 1 ms |
+| `plan_search_strategy` | Recommends which search tool + params for a question.                                        |    ~40 |  ~97 |        < 1 / < 1 ms |
+| `validate_cypher`      | Catches Cypher errors before execution.                                                      |    ~58 | ~116 |            1 / 2 ms |
+| `schema_info`          | Full graph schema: labels, relationships, Cypher examples.                                   |    ~75 |  ~96 |        < 1 / < 1 ms |
+| **Status**             |                                                                                              |        |      |                     |
+| `index_status`         | Projects, entity counts, schema version, index health.                                       |    ~72 |  ~93 |          22 / 23 ms |
+| `list_projects`        | Monorepo project list with dependency relationships.                                         |    ~56 |  ~77 |          12 / 13 ms |
+| `health_check`         | Infrastructure diagnostics: Memgraph, TEI, Valkey, schema.                                   |    ~55 |  ~76 |        218 / 264 ms |
+
+Token counts measured from MCP JSON tool definitions (tiktoken cl100k_base). **Search** = name + description (~966 total); **Full** = name + description + parameter schema with field descriptions, enums, and constraints (~2,945 total). All parameters are self-documented — agents can one-shot any tool without calling `get_usage_guide` first. **Latency** measured with local TEI embeddings on the code-atlas repo (~1,400 entities), 5 iterations, warm embedding cache. See `scripts/profile_query.py`.
 
 ## Quick Start
 
@@ -144,15 +144,15 @@ uv run pre-commit install
 
 ## Performance
 
-| Metric              | Value                 |
-| ------------------- | --------------------- |
-| Parse throughput    | **600–700 files/sec** |
-| Graph search (p50)  | 8 ms                  |
-| BM25 search (p50)   | 10 ms                 |
-| Vector search (p50) | 47 ms                 |
-| Concurrent QPS      | **238** (zero errors) |
+| Metric                     | Value                 |
+| -------------------------- | --------------------- |
+| Full index (107 files)     | **55s** (local TEI)   |
+| Parse-only throughput      | **600–700 files/sec** |
+| `get_node` / `text_search` | 7 ms / 34 ms          |
+| `vector_search`            | 102 ms                |
+| Concurrent QPS             | **238** (zero errors) |
 
-Full benchmark tables and methodology: [docs/benchmarks.md](docs/benchmarks.md)
+Full index includes parsing, graph upserts, and embedding via local TEI (8 concurrent workers). Parse-only is raw tree-sitter CPU time without I/O. Query latencies are averages from `scripts/profile_query.py`. Full benchmark tables: [docs/benchmarks.md](docs/benchmarks.md)
 
 ## Documentation
 

{code_atlas_mcp-0.2.0.dev1 → code_atlas_mcp-0.3.1}/docker-compose.yml

@@ -34,8 +34,12 @@ services:
       - "6379:6379"
     volumes:
       - valkey-data:/data
+    deploy:
+      resources:
+        limits:
+          memory: 384m
     command: >
-      valkey-server --appendonly no --save "" --maxmemory 64mb --maxmemory-policy noeviction
+      valkey-server --appendonly no --save "" --maxmemory 256mb --maxmemory-policy noeviction
     healthcheck:
       test: ["CMD", "valkey-cli", "ping"]
       interval: 10s
@@ -54,6 +58,13 @@ services:
       - "8080:80"
     volumes:
       - tei-models:/data
+    deploy:
+      resources:
+        limits:
+          memory: 4g
+        reservations:
+          memory: 1g
+    command: --auto-truncate
     environment:
       MODEL_ID: ${TEI_MODEL:-Qwen/Qwen3-Embedding-0.6B}
     healthcheck:

{code_atlas_mcp-0.2.0.dev1 → code_atlas_mcp-0.3.1}/docs/adr/0004-event-driven-tiered-pipeline.md

@@ -45,53 +45,50 @@ Redis Streams provide the pub/sub backbone with consumer groups:
 Typed frozen dataclasses with JSON serialization for Redis transport:
 
 - `FileChanged(path, change_type, timestamp)` — published by file watcher
-- `ASTDirty(paths, batch_id)` — published by Tier 1
-- `EmbedDirty(entities: list[EntityRef], significance, batch_id)` — published by Tier 2
+- `EmbedDirty(entities: list[EntityRef], significance, batch_id)` — published by AST stage
 
-### Three-Stream Pipeline
+### Two-Stage Pipeline
 
 ```
-                     atlas:file-changed        atlas:ast-dirty         atlas:embed-dirty
-                          stream                   stream                   stream
-                            │                        │                        │
-                     ┌──────▼───────┐         ┌──────▼───────┐        ┌──────▼───────┐
-  File Watcher ────► │   Tier 1     │ ──────► │   Tier 2     │ ─gate─►│   Tier 3     │
-                     │ Graph Metadata│ always  │  AST Diff +  │ only   │  Embeddings  │
-                     │  (0.5s batch) │         │  Graph Update │ if sig │ (15s batch)  │
-                     └──────────────┘         │  (3s batch)  │ change └──────────────┘
-                                              └──────────────┘
+                     atlas:file-changed                                atlas:embed-dirty
+                          stream                                           stream
+                            │                                                │
+                     ┌──────▼───────┐                                ┌──────▼───────┐
+  File Watcher ────► │  AST Stage   │ ─────── significance gate ───► │ Embed Stage  │
+                     │ hash gate +  │  only if semantically changed  │  Embeddings  │
+                     │ parse + diff │                                │ (15s batch)  │
+                     │  (3s batch)  │                                └──────────────┘
+                     └──────────────┘
 ```
 
-Each tier pulls at its own pace via `XREADGROUP`, deduplicates within its batch window, and publishes downstream only if
-warranted.
+Each stage pulls at its own pace via `XREADGROUP`, deduplicates within its batch window, and publishes downstream only
+if warranted.
 
 ### Per-Consumer Batch Policy
 
-| Tier           | Window | Max Batch | Dedup Key             |
-| -------------- | ------ | --------- | --------------------- |
-| Tier 1 (Graph) | 0.5s   | 50        | File path             |
-| Tier 2 (AST)   | 3.0s   | 20        | File path             |
-| Tier 3 (Embed) | 15.0s  | 100       | Entity qualified name |
+| Stage | Window | Max Batch | Dedup Key             |
+| ----- | ------ | --------- | --------------------- |
+| AST   | 3.0s   | 30        | File path             |
+| Embed | 15.0s  | 100       | Entity qualified name |
 
 Hybrid batching: flush when count OR time threshold hit, whichever first. Same file changed 5× in window = 1 work item.
 
 ### Event Data Flow
 
 ```
-FileChanged                ASTDirty                     EmbedDirty
-┌─────────────┐            ┌──────────────────┐          ┌──────────────────────────┐
-│ path: str   │            │ paths: [str]     │          │ entities: [EntityRef]    │
-│ change_type │ ─Tier 1──► │ batch_id: str    │ ─Tier 2─►│ significance: str        │
-│ timestamp   │            └──────────────────┘   gate   │ batch_id: str            │
-└─────────────┘                                          └──────────────────────────┘
-                                                          EntityRef:
-                                                            qualified_name, node_type,
-                                                            file_path
+FileChanged                                         EmbedDirty
+┌─────────────┐                                     ┌──────────────────────────┐
+│ path: str   │                                     │ entity: EntityRef        │
+│ change_type │ ─── AST stage ── sig gate ────────► │ significance: str        │
+│ timestamp   │                                     └──────────────────────────┘
+└─────────────┘                                      EntityRef:
+                                                       qualified_name, node_type,
+                                                       file_path
 ```
 
-### Significance Gating (Tier 2 → 3)
+### Significance Gating (AST → Embed)
 
-Tier 2 evaluates whether a change is semantically significant enough to warrant re-embedding:
+The AST stage evaluates whether a change is semantically significant enough to warrant re-embedding:
 
 | Condition                   | Level    | Action              |
 | --------------------------- | -------- | ------------------- |
@@ -115,25 +112,25 @@ own retries through this mechanism, avoiding the need for a separate dead-letter
 - Cheap operations (staleness flags, graph metadata) are near-instant — MCP queries reflect changes within ~1s
 - Expensive operations (embeddings) only run when semantically justified — significant cost reduction
 - Decoupled stages can be developed, tested, and scaled independently
-- Batching per tier matches the cost profile of each operation
+- Batching per stage matches the cost profile of each operation
 - Multi-process from day one — no rewrite needed when scaling
 - Dual-use of Valkey for event bus + embedding cache
-- Natural extension point: new tiers or event types can be added without restructuring
+- Natural extension point: new stages or event types can be added without restructuring
 
 ### Negative
 
 - More architectural complexity than a simple "reindex everything on change"
 - Significance threshold heuristics need tuning and may produce false negatives (skipping re-embeds that should have
   happened)
-- Debugging event flow across tiers is harder than a linear pipeline
+- Debugging event flow across stages is harder than a linear pipeline
 - Additional infrastructure dependency (Valkey), though lightweight
 
 ### Risks
 
 - Threshold tuning: too aggressive = stale embeddings, too conservative = excessive TEI calls. Need observability on
   gate decisions.
-- Event ordering: if Tier 2 processes file A before file B, but B depends on A's entities, the diff may be incorrect.
-  Batch boundaries must align with dependency boundaries.
+- Event ordering: if the AST stage processes file A before file B, but B depends on A's entities, the diff may be
+  incorrect. Batch boundaries must align with dependency boundaries.
 - Complexity creep: the event bus must stay simple. If we find ourselves adding routing rules, dead-letter queues, or
   retry logic, we've gone too far.