GroundRecall/docs/architecture.md

Architecture

GroundRecall is the grounded knowledge substrate in a larger stack:

• GroundRecall: canonical knowledge ingestion, promotion, query, export, and future sync
• Didactopus: learner-facing workflows and educational tooling
• GenieHive: model and routing layer where runtime assistant/service resolution is needed

For governed model access, GroundRecall treats the GenieHive Foundation gateway profile as an external endpoint and policy boundary. GroundRecall does not own GenieHive credentials, request audit logs, provider routing, or budget state. See geniehive-foundation-gateway.md.

Core Design

The system is built around one canonical flow:

1. ingest weakly structured sources
2. normalize them into stable knowledge objects
3. lint and queue them for review
4. promote reviewed objects into a canonical store
5. query and export promoted state

Core Objects

The canonical store is built from these object families:

• Source
• Fragment
• Artifact
• Observation
• Claim
• Concept
• Relation
• ReviewCandidate
• PromotionRecord
• GroundRecallSnapshot

These objects are assistant-neutral. Assistant-specific formatting belongs at the adapter layer.

Package Surface

The main standalone package surface is:

• groundrecall.ingest
• groundrecall.lint
• groundrecall.models
• groundrecall.store
• groundrecall.promotion
• groundrecall.query
• groundrecall.export
• groundrecall.assistant_export
• groundrecall.inspect
• groundrecall.source_adapters.*
• groundrecall.assistants.*

There are also compatibility-style helper modules prefixed with groundrecall_ inside the package. Those exist because the standalone repo was extracted from an earlier monorepo layout.

Source Adapters

Adapters handle source-shape-specific discovery and mapping while the downstream pipeline stays generic.

Current adapter families include:

• llmwiki
• markdown_notes
• transcript
• didactopus_pack

Assistant Boundary

Assistant integration is intentionally outside the core store and query semantics.

The rule is:

• core GroundRecall owns truth, provenance, lifecycle, and retrieval semantics
• assistant adapters own presentation, bundle shaping, and tool-specific exports

Current adapters include:

• codex
• claude_code

Alpha Boundary

The current alpha is strong enough for:

• local import and promotion
• canonical query and export
• assistant-neutral bundles
• assistant-targeted bundle generation

It is not yet complete for:

• multi-node sync and merge
• re-import/update semantics
• richer review adjudication
• large-scale distributed corpus integration