Intent
What kind of action, how long it lasts, its stakes, required evidence, clarity, modality and attendance. One request can contain several related pieces of work.
The architecture of Vakyartha
Under
the feathers.
A thoughtful front. A deliberate core.
Follow a request from intent to evidence, with the person in control.
Words & voiceOne governed coreWork & evidence
01 / From words to work
Every step has a reason.
Every action has a boundary.
The model proposes. The runtime validates, authorises and records. A useful answer and a real-world action follow the same accountable path.
- 01
Understand
Read the intent.
Define the outcome. - 02
Admit
Resolve access,
limits and approvals. - 03
Prepare
Select relevant context,
capabilities and route. - 04
Execute
Validate calls.
Dispatch through brokers. - 05
Check
Collect results.
Evaluate the evidence. - 06
Deliver
Present the outcome.
Keep open work visible.
What keeps the path inspectable?
Model-visible inputs are recorded in append-only session history. A turn’s request can be reconstructed from that history. Streaming output preserves partial results on cancellation, and errors remain explicit outcomes. A capability or route decision does not grant new authority.
Read the agent-loop design ↗02 / Intent & commitments
Understand the ask.
Keep the thread.
Intent describes the work. Human authority sets its limits. A commitment gives ongoing work an identity beyond a single conversation.
Outcome
What is wanted, what must be preserved, and what would count as done. That same specification informs execution and verification.
Commitment
A durable goal with progress, constraints, blockers and a completion standard. Quick answers stay lightweight; ongoing work can persist.
The life of ongoing work
- ProposedA goal takes shape
- ActiveWork makes progress
- Waiting or blockedA decision, condition or dependency
- CheckingCompare the result with the criteria
- Closed, with a verdictFulfilled, failed, unknown, or another explicit ending
Reading intent never widens permission
Understanding is fallible. The intent kernel can narrow execution, approval and spending bounds; it cannot create permission. Declared controls and human grants remain separate from inferred meaning.
A commitment is not automatically a scheduled run
A commitment retains the goal and state. Scheduled work uses TaskDef and needs a running installation with suitable access. Clock or condition upkeep can change a commitment’s state without dispatching a model. A recurring workflow needs the actual execution and delivery path configured.
03 / Core, Agents & CorePool
One engine.
More than one workspace.
Core assembles configuration, model access, context, tools, permissions and the agent loop. An Agent owns its identity, conversations and scoped memory. CorePool reuses workspace runtimes with the right policy boundaries.
An authorised channel requestWorkspace + permission override + channel policy
CorePool
Resolve · reuse · cap · evict idle entries
Workspace ACore / policy ATrusted configuration and scoped tools
Workspace ACore / policy BA different override gets its own instance
Workspace BCore / policy CIts own workspace and security ceiling
Reuse without extra authority. Entries are created lazily, bounded in number and evicted when idle. Warm entries recheck persisted permission ceilings.
Agent privacy stays scoped. Sharing a Core or a transport does not grant access to another Agent’s conversations, memory or audience.
04 / The ledger
The story behind
every step.
What did I ask? What did Vakyartha try? What came back? The session ledger keeps a durable record of the conversation and the work around it, so an outcome has a history you can follow.
The request and the response
Messages, tool calls and tool results belong to the session history. Inputs that reach the model must be reconstructable from that record.
The work around the answer
Recorded activity explains approvals, retries and changes of route. Work receipts capture what was dispatched, its attempts, reported usage and outcome.
Ongoing work has a history
Goal and managed-work events preserve how the work progressed. Commitment history adds its lifecycle and completion evidence; FinOps records usage and priced expenditure.
A readable view of the record
The app presents the conversation, progress and result. Technical views reveal more detail. The model receives the relevant conversation context; audit-only receipts and activity are kept out of that input.
What does “append-only” mean?
Normal session activity adds a new entry instead of rewriting an earlier one. Each entry has an identity and a link to its parent. A branch continues from an earlier point while preserving the history it came from.
When a long conversation is condensed for context, that summary is itself recorded. Condensing what the model reads does not silently delete the earlier conversation.
What happens when work stops or takes a different route?
Cancellation preserves partial output. Failures remain explicit outcomes. The session header records the initial admission setup; the work receipt records the actual dispatch for each turn, including attempts and usage. That distinction matters when a later turn uses a different available route.
How do the ledger, memory and spending records fit together?
The session ledger records what happened in a conversation. Memory supports later recall within its authorised scope. Commitment records track ongoing goals, while FinOps helps account for model usage. They answer related questions and keep their own responsibilities.
Conversation history belongs to the Agent. Shared operations and FinOps provide an installation-wide view. Access rules still determine who can see a conversation; connecting a new chat does not grant access to private history.
Where is it kept, and what does the record prove?
Session records are stored on your Vakyartha installation as structured entries. The record supports inspection of the inputs, attempts and evidence the runtime captured. An entry saying an action was attempted still needs a result or receipt to establish what actually happened outside the runtime.
Moving a conversation to Trash hides it from ordinary lists, search and model recall. The current Trash behaviour is not permanent erasure. The data-lifecycle design records track the planned erasure work.
05 / Context management
Keep the whole story.
Bring the useful parts.
Imagine a long conversation about a trip, a document and next week’s plans. When you say “make the second option shorter,” Vakyartha needs the right earlier work and your latest instruction. Context management decides what to bring into that next request.
Make room for the work
The planner uses the model’s capacity profile and available usage evidence. It reserves room for instructions, the current turn and the answer before filling the remaining space with history.
Choose what matters now
Recent work, relevant earlier turns and references such as “the second one” help determine what is brought forward. Related steps stay together as a whole turn.
Condense, with a way back
Older work can become concise cards or a summary covering a named range. Large results can become digests linked to the stored evidence. The model can ask to recall the fuller record.
Reuse what stays the same
Stable instructions and tool definitions come first. Changing information comes later. This structure helps compatible providers reuse cached input, with actual usage recorded.
The techniques behind the scenes
Capacity profiles: provider metadata, available measurements and turn-by-turn feedback inform the usable budget. Hosted capacity probing is opt-in; a measured profile is not available for every model.
Whole-turn selection: the planner weighs recency, relevance and references back to earlier work. It keeps a request and its related exchanges together.
Cards, packets and recall: compact turn cards preserve what was asked, done and produced. Summary packets cover an identified range. Recall can reopen a turn or the evidence behind it.
Stable request prefixes: unchanged instructions and tool schemas stay byte-stable where possible. Receipts record a prefix digest so changes affecting cache reuse can be explained. Caching depends on the provider and workload.
What if the model cannot fit the request?
The working set can be planned again against the available capacity. Oversized evidence is condensed into a meaningful digest with a recall reference instead of being cut at an arbitrary character count. Older originals remain in the ledger.
Summaries and relevance decisions can still miss something important. The recall path makes the source reachable; it does not guarantee perfect recall or understanding. Provider-native compaction remains outside the implemented context engine.
06 / Evidence & evaluations
“Done” needs
something behind it.
A model’s confidence, an observed tool result, and an external receipt carry different weight. Completion is checked against the work’s required evidence.
- 01AssertedModel judgment
- 02CitedSupporting references
- 03ObservedRuntime-checked result
- 04AttestedExternal confirmation
Check the harness
Deterministic evals exercise the production loop, tools, permissions and session records with a scripted provider and temporary workspaces.
vak evalCheck a real model
Live evals ask the configured model to solve verifiable tasks. Reports include results, usage and duration. Provider usage may cost money.
vak eval --liveCheck the actual result
Evals measure the system on test cases. Each real task still needs its own evidence; a green suite does not verify a user’s document or guarantee success.
Explore the evaluation harness ↗07 / Voice
Say it.
Keep the same thread.
Speak a request, hear a reply, or send a voice note through a connected chat. Voice joins the same conversation, with the same permissions and recorded work.
From speech to a governed turn
A completed utterance becomes a transcript in the conversation. The ordinary agent loop handles the request; speech does not grant new authority.
Your voice route
Configure a supported hosted provider or your own local transcription and speech engines. Provider and model choices are explicit. Connected chats can inherit or narrow the workspace’s voice settings.
Voice notes, with context
Telegram, Discord and Slack notes are transcribed after access checks and duplicate detection. The transcript joins the typed message. A transcription failure is reported.
What is available today?
The voice foundation supports utterance-based transcription, spoken replies and channel voice notes when configured. Continuous realtime streaming and physical-microphone acceptance remain open work in the design record. Hosted speech can incur provider charges; local engines must be installed and configured.
08 / FinOps & expenditure
Follow the work.
Follow the spend.
FinOps puts model usage, estimated expenditure and budget admission in the same operational picture. Unknown pricing stays unknown.
- Before a paid call
Check the budget
Apply configured per-run and daily limits before dispatch.
- After the call
Record the usage
Attribute provider, model, session and observed token usage.
- Across the work
Inspect the pattern
Review trends, allocation, pricing coverage and alerts.
What you can see
Provider and model breakdowns, input/output and available cache usage, a daily spending trend, budget alerts and instrumented runtime activity.
What the numbers mean
USD figures are estimates where pricing is available. Unpriced calls are marked unknown, not free. Vakyartha’s usage ledger is not your provider’s final invoice or a cloud-infrastructure billing service.
What happens at a limit?
Budget admission runs before paid dispatch. A limit can block further work or require a decision through the applicable approval path. An unattended request does not gain permission because nobody answers. Limits depend on available usage and pricing evidence; they are not a guarantee of the final provider bill.
09 / The admin & operations console
See the system.
Know where to look.
The secured admin console is served by the same Vakyartha installation. Move from an overview to a resource, incident or recorded result without creating a second source of truth.
Admin console
On your secured installation
/admin- Work & attention
- Conversations, commitments, active work, inbox and approvals.
- FinOps
- Expenditure estimates, usage, allocation, limits and pricing coverage.
- Configuration & access
- Providers, tools, prompts, permissions, Agents and channel connections.
- Operations
- CorePool, services, scheduled work, delivery, incidents and Doctor checks.
The everyday app focuses on the conversation and result. Admin exposes the controls and evidence behind it. Changing the surface never grants permission to bypass execution rules.
Explore the admin and operations design ↗10 / Meet Doctor
A little check-up.
A clearer next step.
Something not working? Doctor looks through your Vakyartha installation, brings the failed checks together, and tells you what needs attention.
Start with a diagnosis
Check provider setup, configuration, saved-work storage, voice readiness, capabilities, channel bindings and installation consistency. The command also reports managed services that have exited with an error.
vak doctorUnderstand the next step
A missing voice model needs a model choice. An unreachable workspace needs the right location. Doctor reports the problem so you can make that decision with context.
Repair what has a known fix
When you ask for repair, Doctor applies supported mechanical fixes, reports each attempt, then checks again. Provider credentials and configuration decisions stay with you.
vak doctor --repairWhich repairs can Doctor make?
Current repairs cover installation version mismatch, cleanup of retired plugins, and denying pending channel requests that have passed their configured expiry. Expired requests remain visible with their reason. An approved channel pointing to a missing workspace needs an operator to choose the correct location.
Repair is an explicit action and can change the installation or channel state. Run the diagnosis first to see what needs attention.
Where else can I see the check-up?
The terminal’s /doctor command and the secured admin Operations Center use the same core health report. Operations combines that report with service, delivery and incident state. These are checks on your installation; a passing report does not guarantee every external service or future request will succeed.
11 / Surfaces, channels & deployment
At your desk.
On a server you choose.
The headless core can run locally or on a self-managed Linux host. Desktop, browser, terminal and connected chats reach governed execution through their own authenticated paths.
DesktopBrowserTerminal / APITelegram · Slack · Discord
Authentication · authorised endpoint · scoped audience
Your Vakyartha host
Server · CorePool · Agents · local state
Permissions and budget checks before execution
Configured AI servicesBrokered tools & workersScoped integrations
Local or self-hosted cloud
Run the server on macOS or Linux, including a Linux VM you manage. Loopback is the default. Remote access needs an explicit tunnel or configured hostname, authentication and appropriate TLS.
Surfaces are not identities
An Agent owns a conversation. A bot supplies a transport identity; a channel is an endpoint. Multiple bots in one chat keep separate bindings and policy. Connecting accounts does not automatically share history or access.
Execution stays bounded
File and shell tools cross broker boundaries. Restricted execution uses available OS sandboxing or configured Docker semantics. Full access is an explicit human decision, never an automatic fallback.
Distributed messaging, when configured
The optional message fabric supports an in-memory backend and NATS/JetStream for distributed events and work transport. CorePool itself is an in-process runtime pool, not a cluster scheduler. Deployment capacity depends on the host, providers and workload.
Services have an owner
launchd or systemd manages durable service recovery. Operations reports service and delivery state; it does not replace the operating system’s process manager.
Cloud roadmap, clearly separate
Self-hosting is available today. Cloud-remote storage and session handoff remain planned work; their design records describe the next steps.
Completely open source.
Nothing hidden
under the feathers.
The runtime, interfaces, design records and evaluation harness are yours to read, run and build on under the MIT License.
Explore the source Set up Vakyartha ↗Conceptual diagrams describe the architecture. Feature-specific setup and limits still apply.