Architecture

Eight layers, three databases, one runtime contract. Syntax is deterministic. Meaning is agent-driven. Every claim carries its grounding.

Layered model

The layers map loosely onto the DIKW pyramid: raw data at the bottom, derived meaning at the top. Each layer has its own SQLite table family. Edges cross layers explicitly via foreign keys.

Scope × grounding

Two tags on every knowledge node keep objective fact separate from inference. They are the mechanism behind "based on facts, never assume."

scope — technical (architecture) · industry (business domain) · meta.

Project-truth queries default to structural / stated / corroborated. external and model are opt-in and always filterable, so "fill the gap" knowledge never gets mistaken for what your project actually does. codegps status breaks every layer down by both scope and grounding.

Pipeline

Each ingest run pulls new turns, segments them into windows, and routes each window through the deterministic syntax pass and the agent stack. Inputs flow top-down; outputs accumulate as edges back into earlier layers.

Enrichment stages (L2.5)

• Manifest parser — walks the project (depth-limited) for dependency manifests and infra files; emits dependency / tool facts (structural). Monorepos with nested manifests are fully covered.
• Domain-from-code — promotes SQL tables to entity facts and foreign keys to relates_to edges (structural).
• Reconciler — matches stated entities to structural ones by normalized name; links same_as and upgrades grounding to corroborated.
• TechnicalProfiler — synthesizes higher-level skills from languages + declared dependencies.
• IndustryClassifier / IndustryEnricher — names the business domain from any available signal; proposes industry-standard concepts as model/external learning targets.
• Gap detector — evidence-cited knowledge_gap nodes; names the gap, never the answer.

Deterministic stages

• Window Segmenter — slices a session into windows on user-turn boundaries with size and time caps.
• Syntax Pass — extracts artifacts that are unambiguous from form: paths, code blocks, shell commands, error messages, stack traces, URLs, ticket IDs.
• Code Resolver — for any mention (syntax or agent), look it up in code.db and write a k_to_code edge.

Agent stages

• Triage — drops noise and labels each window on four axes.
• Dedupe — embedding similarity against prior windows and prior facts.
• Extractors — Decision, BusinessLogic, Intent, ProblemSolution. Routed by triage domain so business-logic agents don't waste tokens on chitchat.
• Clusterer — for each new fact, picks attach / create / merge against top-K nearest concepts.
• Summarizer — names and writes a structured summary for each touched concept.
• Linker — proposes cross-project links the mechanical pass missed.
• Verifier — periodic sweep for contradictions, supersessions, low-confidence pruning.

The agent layer

There are eighteen chat agents and one embedding-only agent. Each has a versioned prompt, a JSON schema, and a model reference resolved from config. All share a single runtime that handles caching, validation, and persistence. Agent-bound calls run with bounded concurrency (config.concurrency).

Agent runtime

Every agent call goes through one function. Inputs are a typed payload plus the agent's prompt and schema; outputs are validated JSON, cached by content hash, and persisted to agent_runs for audit.

interface Agent<I, O> {
  name: string;
  promptVersion: number;        // bump invalidates cache
  modelKey?: string;            // overrides config lookup
  schema: JsonSchema;           // strict validation
  prompt(input): ChatMessage[];
  postprocess?(o, input): { output, confidence };
}

interface AgentRuntime {
  run<I, O>(agent, input): Promise<{ output, confidence, model, cached }>;
  // 1. hash(agent.name + model + prompt_version + input) -> cache lookup
  // 2. call backend (Ollama / OpenAI-compatible / Anthropic)
  // 3. parse JSON; validate against schema; one repair retry on failure
  // 4. write to agent_runs (success or failure)
}

Cache invariants

• Same input + same model + same prompt version → cached hit, zero cost
• Bump promptVersion → all prior runs ignored, agent re-runs
• Swap model in config → cache miss only for affected agent; others unchanged

Storage

<project>/.codegps/
├── code.db          # L0 — codegraph-compatible schema
│   ├── nodes              (id, kind, name, qualified_name, file_path, ...)
│   ├── edges              (source, target, kind, line, col, provenance)
│   ├── files              (path, content_hash, indexed_at, ...)
│   ├── file_analysis      (L0.5 — summary, layer, tags per file)
│   ├── nodes_fts          (FTS5 over names / signatures / docstrings)
│   └── unresolved_refs
│
├── knowledge.db     # L1, L1.5, L2, L2.5, L3 + agent cache
│   ├── sessions / turns / tool_calls
│   ├── turns_fts          (FTS5 over turn text)
│   ├── turn_windows / triage_labels
│   ├── k_nodes            (+ scope, grounding, source_url columns)
│   ├── k_edges / k_provenance / k_to_code
│   ├── k_nodes_fts        (FTS5 over fact titles + summaries)
│   ├── k_node_embeddings  (sidecar — keeps k_nodes lean)
│   ├── concepts           (+ scope, grounding columns)
│   ├── research_cache     (external lookups, opt-in)
│   └── agent_runs         (cache + audit)
│
└── canvas/          # generated .canvas.tsx artifacts

~/.codegps/
├── global.db
│   ├── projects
│   ├── concepts_global    (mirrors per-project concepts with embeddings)
│   ├── concept_links      (a, b, kind, score, source)
│   ├── skills             (L5 — name, scope, evidence_weight, project_count)
│   ├── skill_evidence     (per-project evidence behind each skill)
│   ├── industries         (classified business domains across projects)
│   ├── highlights         (composite portfolio statements per project)
│   └── agent_runs         (cache + audit for global agents, e.g. ProfileWriter)
└── config.json

Three databases, three responsibilities. The split keeps the code DB drop-in for codegraph users and lets the knowledge schema evolve independently. Knowledge-schema columns (scope, grounding, …) are added via additive migrations, so existing databases upgrade in place.

Languages

Adding a language: a new entry in src/code/languages.ts plus ~50 lines of node-type handlers in src/code/extractor.ts. Tree-sitter WASMs for Swift, Kotlin, PHP, Ruby, C, and C++ are already shipped in tree-sitter-wasms and only need wiring.

Conversation sources

Design trade-offs

• Local-only. No cloud sync. The hard runtime dependency is a local (or pluggable) LLM. The alternative would be regex-based NL understanding, which drifts the moment anyone tries to maintain it.
• Cached, not deterministic. Agent output is stable per (agent, model, input_hash, prompt_version). Bumping the prompt version invalidates the cache by design.
• Incremental clustering. The Clusterer attaches greedily and may drift; codegps link --rebuild triggers a full recompute when the drift becomes visible.
• Pull-based ingest. No real-time chat hooks; re-run codegps ingest (or call codegps_ingest via MCP) to pick up new sessions.
• Code DB stays codegraph-compatible. New code-side fields go in project_metadata JSON rather than schema changes.
• Conservative triage by default. Windows are kept unless an axis is firmly negative with confidence ≥ 0.6. triage audit --dropped lets you tune.