Architecture
An infrastructure layer, not a chat interface
Venkai has no conversational surface of its own. It is a pipeline that turns a company's data into a structure other AI systems query — the same shape as a database or an identity provider, not a product a team logs into.
Architecture
Seven stages. Five of them run today.
The actual shape of the system, not an illustration of one. Operational runs today and is covered by the benchmark below. Specified is specified, not built yet.
- 01 · INPUTOperational
Sources
Source trees, documents and structured records, read where they already live. Nothing is uploaded and nothing is mirrored — the engine runs on the machine that owns the files.
Local filesystem · Git working tree
- 02 · PARSEOperational
Structural extraction
Each file is parsed into a concrete syntax tree, not scanned as text. Symbols, their spans, their decorators and their enclosing scope are resolved from the grammar, so a method keeps its class and a decorator stays part of the symbol it decorates.
AST parser · symbol resolver
- 03 · RELATEOperational
Symbol & dependency graph
Symbols are linked into a persistent graph of definitions, references and call edges. This is what turns an instruction that names one function into a bounded set of places that can legally change.
Symbol graph · project_graph.json
- 04 · REASONOperational
Semantic operation engine
A model describes an intent; the engine turns it into a typed operation — replace, insert-after, delete-range — and derives the minimum-cost plan that satisfies it. The model never emits the code itself.
Semantic operation schema · minimal-patch planner
- 05 · PROVEOperational
Verification & rollback
Before anything touches disk: refuse on an ambiguous anchor, refuse when a decorator would be dropped, re-parse after applying, and roll the transaction back if the file no longer compiles. Failure is a refusal, never a partial write.
Neuro-symbolic guard · transactional apply
- 06 · GENERALISESpecified
Knowledge representation
Extending the same graph beyond code, so that specifications, schemas and prose participate in the same resolution. The interface is specified against the existing graph; the extractors for non-code sources are not built.
Specified — not implemented
- 07 · SERVESpecified
Agent & application interface
A model-agnostic API so any agent can describe a change instead of writing one. Today the engine is driven in-process by our own tooling; the packaged interface, the installer and account linking are being built.
In development
Architecture
Where this differs from adjacent approaches
vs. classic RAG
Retrieval-augmented generation embeds documents and returns the passages closest to a query at inference time. That surfaces text that resembles a question; it has no representation of which passage is current, what superseded it, or how two passages relate. Venkai's entity graph stores those relationships explicitly, as structure — not as a hope that embedding distance happens to encode them.
vs. a vector database alone
A vector database is a storage and retrieval primitive — nearest-neighbor search over embeddings. It is a genuinely useful building block, and it is one layer below where Venkai operates: Venkai's entity graph and persistent context engine sit on top of whatever retrieval primitive is in use, adding the relational structure that similarity search cannot represent on its own.
vs. simple chat memory
Chat-app memory is scoped to one user's conversations with one product. Venkai's persistent context engine is scoped to the organization: the same structured context is available to every AI system the company runs, permissioned the same way the source systems already are, and it does not reset when a team switches products or model vendors.
Architecture
Data, stated plainly
Where data lives
On the machine that already owns it. The engine runs against the local filesystem and Git working tree — nothing is uploaded, nothing is mirrored to Venkai's infrastructure. This is true today, for the SME engine; it is a design constraint carried into every future stage, not something that changes as the product grows.
Stored vs. temporary
Today: the symbol/dependency graph is a per-run local artifact (project_graph.json) — it is rebuilt, not persisted, between sessions. Persistent, cross-session storage is the 'Knowledge representation' stage in the pipeline above, and it is designed, not built: the interface is specified, the extractors are not implemented yet.
How context evolves / how multiple models share it
Not solved today — this is the 'Agent & application interface' stage above, also designed and not built. The intended shape is a model-agnostic API so any agent describes a change instead of writing one; today the engine is driven in-process by Venkai's own tooling only.