droste-memory 1.0.0__tar.gz

droste_memory-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing to Droste
+
+Thanks for helping build the causal-memory layer for AI agents.
+
+## Dev setup
+
+```bash
+git clone <your fork>
+cd droste-memory
+pip install -e ".[dev]"
+pytest                 # should be green before you start
+```
+
+## Ground rules
+
+- **Tests stay green.** `pytest` runs the deterministic regression suite
+  (`tests/`). Add a test for any behaviour change to the engine, ingester, or
+  packer. The suite forces the deterministic hash embedding backend, so it runs
+  offline with no model download.
+- **`eval/` is for benchmarks, `tests/` is for invariants.** Don't mix them.
+- **Keep the zero-config moat.** New required deps are a big deal — prefer
+  optional extras. `fastembed` (no torch) and `tree-sitter-language-pack` are the
+  only heavy runtime deps and both degrade gracefully if missing.
+- **Never commit user data.** `droste_memory_db.json`, `.droste/`,
+  `visualizer/graph.json` and `status.json` are gitignored — they can contain a
+  user's source. Only `visualizer/demo_graph.json` (Droste indexing itself) is
+  public.
+
+## Good first issues
+
+- New language extractor / edge rules in `core/treesitter_extract.py`.
+- More cross-language bridges in `core/droste_ingester.py`
+  (`_build_dependency_links`) — e.g. ORM table refs, GraphQL, gRPC.
+- Visualizer polish in `visualizer/cockpit.html`.
+
+## PRs
+
+Small, focused, with a one-line rationale and a test. CI runs `pytest` on
+Linux across Python 3.10–3.12.

droste_memory-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Droste-Memory authors
+
+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.

droste_memory-1.0.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md LICENSE CONTRIBUTING.md requirements.txt
+recursive-include visualizer *.html *.py *.json
+prune visualizer/graph.json
+prune visualizer/status.json

droste_memory-1.0.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: droste-memory
+Version: 1.0.0
+Summary: Local hybrid structural and semantic graph memory engine.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: fastembed>=0.8.0
+Requires-Dist: truststore>=0.10.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: uvicorn[standard]>=0.27.0
+Requires-Dist: tree-sitter>=0.23.0
+Requires-Dist: tree-sitter-language-pack>=1.9.0
+Provides-Extra: heavy-embed
+Requires-Dist: sentence-transformers>=2.7.0; extra == "heavy-embed"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# Droste
+
+### See your codebase as a living galaxy — and give your agents causal memory of it.
+
+Droste indexes any repo into a fractal, zoomable map of its symbols, wires them
+together with their real call / import / DB edges across languages, and serves an
+agent the *causal* slice of code it actually needs — not just keyword matches.
+
+**Local-first · zero-config · polyglot · MCP-native**
+
+![Droste fractal code galaxy](docs/assets/hero.gif)
+
+*Zooming out reveals the causal web — every cyan arc is a real `syntax_dependency`
+edge. [Full flythrough (FastAPI)](docs/assets/demo.mp4)*
+
+[Quickstart](#quickstart) · [Why it's different](#why-its-different) · [How it works](#how-it-works) · [MCP](#use-it-as-an-mcp-server) · [Benchmarks](#benchmarks)
+
+</div>
+
+---
+
+## Quickstart
+
+```bash
+pip install -e .          # or: pip install droste-memory   (once on PyPI)
+droste index .            # index the current repo
+droste view               # open the fractal galaxy in your browser
+```
+
+Three commands. `droste view` opens a full-screen, 60fps zoomable map of your
+code — scroll to dive from the project star into folder orbits, down to the
+individual functions, with the causal edges glowing between them.
+
+Need it for an agent instead of your eyes?
+
+```bash
+droste context "checkout flow" --budget 1500   # causal context slice for an LLM
+```
+
+Running `droste` with no arguments prints the command palette:
+
+```text
+                  .-----------------------.
+             .----'           |           '----.
+         .---'          .-----+-----.          '---.
+       .'          .----'     |     '----.          '.
+      /        .---'      .---+---.      '---.        \
+     /      .-'        .-'    |    '-.        '-.      \
+    |     .'        .-'   .---+---.   '-.        '.     |
+    |    /        .'    .'    |    '.    '.        \    |
+    |   |        |     |   .--+--.   |     |        |   |
+    | --+--------+-----+---+  @  +---+-----+--------+-- |
+    |   |        |     |   '--+--'   |     |        |   |
+    |    \        '.    '.    |    .'    .'        /    |
+    |     '.        '-.   '---+---'   .-'        .'     |
+     \      '-.        '-.    |    .-'        .-'      /
+      \        '---.      '---+---'      .---'        /
+       '.          '----.     |     .----'          .'
+         '---.          '-----+-----'          .---'
+             '----.           |           .----'
+                  '-----------------------'
+
+DROSTE-MEMORY // RIGID FRACTAL RADIAL LAYOUT
+Local Graph Engine v1.0-Alpha-Sharded
+
+Commands
+  droste index <path> [--reset]
+  droste status
+  droste zoom <symbol_name>
+  droste context [query] --budget 1500
+
+Fast path: droste context hub_core --budget 1000 | clip
+```
+
+---
+
+## Why it's different
+
+Most "code context" tools rank by keyword (ctags / ripgrep / repo-maps) or by
+embedding cosine (vector-RAG). Both can only return what *resembles* your query.
+A caller that shares no tokens — or a database function in a different language —
+is invisible to them, yet it's exactly what you need to understand or change the
+code.
+
+Droste's edge is the causal graph:
+
+- **Causal wormholes.** Real `syntax_dependency` edges (calls, imports,
+  inheritance) in both directions — Droste hands the caller and callees, ordered,
+  within a token budget.
+- **Cross-language bridges.** The part nobody else does well: Droste links across
+  languages — app code to SQL functions/tables (`.rpc('x')`, `.from('table')`),
+  to edge functions, and same-name handlers between any two languages. Your
+  Dart/TS/Python frontend and your database stop being two separate worlds on the
+  map.
+- **A map you actually want to look at.** The fractal galaxy isn't a gimmick —
+  it's how you see coupling, risk hotspots, and the blast radius of a change.
+- **Zero-config and local.** No cloud, no account, no API key. fastembed (ONNX,
+  no torch) gives real semantics; a deterministic fallback keeps it runnable
+  anywhere.
+
+Polyglot: Python (AST) + tree-sitter for Dart, TypeScript/JavaScript, Go, Rust,
+Java, C#, C/C++, Kotlin, Swift, Ruby, PHP, SQL — symbols *and* edges.
+
+> **Honest scope:** the measured advantage is structural / causal retrieval. On
+> pure semantic "concept" queries it's competitive with a vector baseline, not a
+> leap. Cross-language bridges are strongest where the target is actually defined
+> in the indexed repo (e.g. SQL schema in your migrations).
+
+---
+
+## Benchmarks
+
+Self-supervised eval (gold = the true caller/callee set from the AST), equal
+retrieval breadth *k*, real embeddings, across Python + Dart repos
+(`eval/comparative_eval.py`):
+
+| structural retrieval | Droste | vector-RAG core | lexical core |
+| --- | --- | --- | --- |
+| neighbour-recall | **0.94** | 0.18 | 0.42 |
+| nDCG@k | **0.65** | 0.10 | 0.29 |
+
+…plus hundreds of true causal neighbours that both baselines structurally miss.
+This is a retrieval-method comparison (the cores of vector-RAG and lexical
+search), not a head-to-head against the finished products that wrap them.
+
+---
+
+## How it works
+
+- **Causal graph.** Each definition is parsed (Python `ast`; tree-sitter for the
+  rest) into the names it calls / imports / inherits, becoming first-class
+  `syntax_dependency` edges. Cross-language edges add DB calls (`.rpc`, `.from`,
+  `.functions.invoke`) and string-literal name matches across languages.
+- **Hybrid seed.** A query is matched by a normalized blend of lexical score and
+  semantic cosine (fastembed `bge-small-en-v1.5`, 384-dim), then the graph
+  expands the seed bidirectionally (callees and callers).
+- **Token packer.** Results fit a budget with LOD-demotion (full to contract to
+  skeleton) and a hard guardrail that never cuts a line of code mid-token.
+- **Sharded persistence.** One shard per file under `.droste/`, blake2b
+  dirty-tracking so a re-index rewrites only what changed; atomic writes + meta
+  written last, so it is crash-safe and self-heals on the next run.
+
+---
+
+## Use it as an MCP server
+
+Droste is a drop-in MCP server — an agent calls it as primary code memory instead
+of blind file reads.
+
+```jsonc
+{
+  "mcpServers": {
+    "droste": { "command": "python", "args": ["/abs/path/to/droste-memory/server.py"] }
+  }
+}
+```
+
+Key tools: `droste_index_project`, `droste_get_context`, `droste_status`.
+
+---
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest                            # deterministic regression suite (tests/)
+python eval/comparative_eval.py   # retrieval benchmark vs lexical & vector cores
+```
+
+`tests/` = invariants + concurrency (round-trip, dirty-oracle, packer guardrail,
+cross-process shard race). `eval/` = performance/quality benchmarks.
+
+---
+
+## Status
+
+**v1.0.0a0 (alpha).** Engine, polyglot + cross-language graph, CLI, fractal
+visualizer and MCP server are working and tested. Packaging/distribution are
+maturing — issues and PRs welcome (see `CONTRIBUTING.md`).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

droste_memory-1.0.0/README.md

@@ -0,0 +1,185 @@
+<div align="center">
+
+# Droste
+
+### See your codebase as a living galaxy — and give your agents causal memory of it.
+
+Droste indexes any repo into a fractal, zoomable map of its symbols, wires them
+together with their real call / import / DB edges across languages, and serves an
+agent the *causal* slice of code it actually needs — not just keyword matches.
+
+**Local-first · zero-config · polyglot · MCP-native**
+
+![Droste fractal code galaxy](docs/assets/hero.gif)
+
+*Zooming out reveals the causal web — every cyan arc is a real `syntax_dependency`
+edge. [Full flythrough (FastAPI)](docs/assets/demo.mp4)*
+
+[Quickstart](#quickstart) · [Why it's different](#why-its-different) · [How it works](#how-it-works) · [MCP](#use-it-as-an-mcp-server) · [Benchmarks](#benchmarks)
+
+</div>
+
+---
+
+## Quickstart
+
+```bash
+pip install -e .          # or: pip install droste-memory   (once on PyPI)
+droste index .            # index the current repo
+droste view               # open the fractal galaxy in your browser
+```
+
+Three commands. `droste view` opens a full-screen, 60fps zoomable map of your
+code — scroll to dive from the project star into folder orbits, down to the
+individual functions, with the causal edges glowing between them.
+
+Need it for an agent instead of your eyes?
+
+```bash
+droste context "checkout flow" --budget 1500   # causal context slice for an LLM
+```
+
+Running `droste` with no arguments prints the command palette:
+
+```text
+                  .-----------------------.
+             .----'           |           '----.
+         .---'          .-----+-----.          '---.
+       .'          .----'     |     '----.          '.
+      /        .---'      .---+---.      '---.        \
+     /      .-'        .-'    |    '-.        '-.      \
+    |     .'        .-'   .---+---.   '-.        '.     |
+    |    /        .'    .'    |    '.    '.        \    |
+    |   |        |     |   .--+--.   |     |        |   |
+    | --+--------+-----+---+  @  +---+-----+--------+-- |
+    |   |        |     |   '--+--'   |     |        |   |
+    |    \        '.    '.    |    .'    .'        /    |
+    |     '.        '-.   '---+---'   .-'        .'     |
+     \      '-.        '-.    |    .-'        .-'      /
+      \        '---.      '---+---'      .---'        /
+       '.          '----.     |     .----'          .'
+         '---.          '-----+-----'          .---'
+             '----.           |           .----'
+                  '-----------------------'
+
+DROSTE-MEMORY // RIGID FRACTAL RADIAL LAYOUT
+Local Graph Engine v1.0-Alpha-Sharded
+
+Commands
+  droste index <path> [--reset]
+  droste status
+  droste zoom <symbol_name>
+  droste context [query] --budget 1500
+
+Fast path: droste context hub_core --budget 1000 | clip
+```
+
+---
+
+## Why it's different
+
+Most "code context" tools rank by keyword (ctags / ripgrep / repo-maps) or by
+embedding cosine (vector-RAG). Both can only return what *resembles* your query.
+A caller that shares no tokens — or a database function in a different language —
+is invisible to them, yet it's exactly what you need to understand or change the
+code.
+
+Droste's edge is the causal graph:
+
+- **Causal wormholes.** Real `syntax_dependency` edges (calls, imports,
+  inheritance) in both directions — Droste hands the caller and callees, ordered,
+  within a token budget.
+- **Cross-language bridges.** The part nobody else does well: Droste links across
+  languages — app code to SQL functions/tables (`.rpc('x')`, `.from('table')`),
+  to edge functions, and same-name handlers between any two languages. Your
+  Dart/TS/Python frontend and your database stop being two separate worlds on the
+  map.
+- **A map you actually want to look at.** The fractal galaxy isn't a gimmick —
+  it's how you see coupling, risk hotspots, and the blast radius of a change.
+- **Zero-config and local.** No cloud, no account, no API key. fastembed (ONNX,
+  no torch) gives real semantics; a deterministic fallback keeps it runnable
+  anywhere.
+
+Polyglot: Python (AST) + tree-sitter for Dart, TypeScript/JavaScript, Go, Rust,
+Java, C#, C/C++, Kotlin, Swift, Ruby, PHP, SQL — symbols *and* edges.
+
+> **Honest scope:** the measured advantage is structural / causal retrieval. On
+> pure semantic "concept" queries it's competitive with a vector baseline, not a
+> leap. Cross-language bridges are strongest where the target is actually defined
+> in the indexed repo (e.g. SQL schema in your migrations).
+
+---
+
+## Benchmarks
+
+Self-supervised eval (gold = the true caller/callee set from the AST), equal
+retrieval breadth *k*, real embeddings, across Python + Dart repos
+(`eval/comparative_eval.py`):
+
+| structural retrieval | Droste | vector-RAG core | lexical core |
+| --- | --- | --- | --- |
+| neighbour-recall | **0.94** | 0.18 | 0.42 |
+| nDCG@k | **0.65** | 0.10 | 0.29 |
+
+…plus hundreds of true causal neighbours that both baselines structurally miss.
+This is a retrieval-method comparison (the cores of vector-RAG and lexical
+search), not a head-to-head against the finished products that wrap them.
+
+---
+
+## How it works
+
+- **Causal graph.** Each definition is parsed (Python `ast`; tree-sitter for the
+  rest) into the names it calls / imports / inherits, becoming first-class
+  `syntax_dependency` edges. Cross-language edges add DB calls (`.rpc`, `.from`,
+  `.functions.invoke`) and string-literal name matches across languages.
+- **Hybrid seed.** A query is matched by a normalized blend of lexical score and
+  semantic cosine (fastembed `bge-small-en-v1.5`, 384-dim), then the graph
+  expands the seed bidirectionally (callees and callers).
+- **Token packer.** Results fit a budget with LOD-demotion (full to contract to
+  skeleton) and a hard guardrail that never cuts a line of code mid-token.
+- **Sharded persistence.** One shard per file under `.droste/`, blake2b
+  dirty-tracking so a re-index rewrites only what changed; atomic writes + meta
+  written last, so it is crash-safe and self-heals on the next run.
+
+---
+
+## Use it as an MCP server
+
+Droste is a drop-in MCP server — an agent calls it as primary code memory instead
+of blind file reads.
+
+```jsonc
+{
+  "mcpServers": {
+    "droste": { "command": "python", "args": ["/abs/path/to/droste-memory/server.py"] }
+  }
+}
+```
+
+Key tools: `droste_index_project`, `droste_get_context`, `droste_status`.
+
+---
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest                            # deterministic regression suite (tests/)
+python eval/comparative_eval.py   # retrieval benchmark vs lexical & vector cores
+```
+
+`tests/` = invariants + concurrency (round-trip, dirty-oracle, packer guardrail,
+cross-process shard race). `eval/` = performance/quality benchmarks.
+
+---
+
+## Status
+
+**v1.0.0a0 (alpha).** Engine, polyglot + cross-language graph, CLI, fractal
+visualizer and MCP server are working and tested. Packaging/distribution are
+maturing — issues and PRs welcome (see `CONTRIBUTING.md`).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

droste_memory-1.0.0/core/__init__.py

@@ -0,0 +1,6 @@
+"""Core package for Droste-Memory."""
+
+from .droste_engine import DrosteConceptEngine, DrosteNode
+from .droste_ingester import DrosteProjectIngester
+
+__all__ = ["DrosteConceptEngine", "DrosteNode", "DrosteProjectIngester"]