System Architecture
DAMS is organized into three cooperating layers — Memory, Intelligence, and Discovery — plus a tool-binding surface (OS shims + MCP) that keeps agents on the context fast path.
Layer overview
| Layer | Components | Role |
|---|---|---|
| Memory | Context Wiki, Context Compiler, DAMS CLI, SKILL.md | What was decided, what's broken, what's next |
| Intelligence | Safety Gate, Drift Detection, CodeGraph, LSP-MCP, GitHub/GitLab MCP, Git Context | Validate, navigate, prevent |
| Discovery | Chunkhound, cAST chunking, Ollama embeddings + reranker, DuckDB, post-retrieval pruner | Find relevant code by concept |
The 5-Tier Dispatcher Pipeline
The context dispatcher (context_dispatcher.py) routes search queries through a
cascade so common, high-signal lookups never touch the vector DB:
| Tier | Mechanism | Purpose |
|---|---|---|
| 0 — AST Fast-Path | Regex match for CamelCase/PascalCase/snake_case identifiers → Graphify AST | Instant symbol lookup, bypasses vector DB |
| 1 — SQLite FTS5 | Full-text search over symbol_index | Exact method/class/attr in <50ms |
| 2 — Graphify→Chunkhound | Trace symbol in dependency graph, fetch adjacent lines via Chunkhound | Architecturally aware retrieval |
| 3 — Semantic RAG | Natural-language query → embeddings → DuckDB cosine similarity | Concept search |
| 4 — Grep/Ripgrep | Subprocess passthrough | Zero-failure terminal fallback |
Graphify-First retrieval
DAMS grounds search in the knowledge graph before touching Chunkhound. For a selected
task, it (1) queries Graphify for a topological subgraph, (2) injects that structure into
query generation, (3) resolves real node names via Graphify, then (4) runs targeted
Chunkhound retrieval into a scratchpad (codeResearch.md). BFS subgraph queries
achieve a 71.5× token reduction versus naive file dumps.
Tool-binding surface
Two complementary mechanisms keep agents off brute-force scanning:
- OS-level shims — thin bash wrappers for
grep,rg,find,fd,sgthat intercept calls, check~/.dams_shims_enabled, route to the dispatcher, and log. - MCP Interception Proxy — a protocol-level proxy that wraps any underlying MCP server and catches native tool calls (
grep_search,view_file,list_dir), returning rich Graphify/Chunkhound context.
Deployment topology
| Service | In container | On host |
|---|---|---|
| Vite / React UI | 5174 | 5174 |
| FastAPI backend | 8765 | 8765 |
| Ollama | 11434 | 11435 |
The backend default port is 8765 (not 8000) to avoid colliding with Portainer;
the Vite dev server is pinned to 5174 with strictPort: true.
DAMS-FT: Fine-Tuned Codebase Intelligence
DAMS-FT (Fine-Tuned Edition) adds a specialized, fine-tuned local intelligence layer to DAMS, powered by a custom Bonsai-8B model and the Gortex AST knowledge graph daemon.
Key Advantages of DAMS-FT:
| Metric | DAMS-Base | DAMS-FT |
|---|---|---|
| Tool Selection Accuracy | ~82.4% | 100.0% |
| Routing Latency | 1,200-2,500ms | <300ms |
| Token Savings | Baseline | 27-40% |
| Security | Post-execution | PreToolUse Blocking |
DAMS-FT utilizes the GCX1 Wire Protocol for token-compressed serialization and implements a PreToolUse Security Shield that intercepts and redirects native tool calls to Gortex AST alternatives.
See the full DAMS-FT documentation for details on the 28-tool Gortex surface, benchmark results, and enterprise deployment.