Graph-lite DX: typed schema + typed query (nanograph-inspired) #98
Description
Summary
Improve graph/structured-memory developer experience by adding a typed schema + typed query surface for ELF's graph-lite pathway, inspired by nanograph's .pg + .gq ergonomics, without adopting an embedded graph DB or changing ELF's SoT model.
Why now
Our 2026-03-03 deep-dive refresh highlights that ELF's graph-lite direction exists, but the human/developer ergonomics are behind typed graph-first tools (nanograph).
Evidence
- README.md:132 (ELF graph-lite is present, optional
relation_context) - README.md:134 (nanograph scope isn't directly comparable; still useful for DX ideas)
- README.md:148 (nanograph signature strength: typed schema + typed query)
- docs/research/comparison_external_projects.md:479 (nanograph deep dive)
Primary upstream references
- https://github.com/aaltshuler/nanograph
- https://github.com/aaltshuler/nanograph/blob/main/docs/user/schema.md
- https://github.com/aaltshuler/nanograph/blob/main/docs/user/queries.md
Proposal (ELF)
- Define a typed graph-lite schema for entities/relations (Rust types + JSON schema) with explicit validation at ingest.
- Define a typed query surface for relation-heavy recall (start as structured JSON query / builder; only later consider a DSL).
- Provide explain/trace output for relation_context assembly (what relations, why included, any truncation).
- Keep it optional and additive: existing note search remains unchanged; this is an opt-in path.
Non-goals
- Adopting a graph database backend or embedding nanograph itself.
- Benchmark/performance claims; focus on correctness + DX + debuggability.
Acceptance (for first iteration)
- A concrete schema + validation rules documented in docs/spec and enforced in API boundary.
- A minimal query contract that can be used via HTTP + MCP without custom client code.
- Unit tests covering schema validation and a few query/explain cases.