Voiden

Type: ../types/agent-memory-system-review.md · Status: current

Voiden is VoidenHQ's offline, Git-native API workspace for building, testing, documenting, and collaborating on APIs through plain-text .void files. It is not primarily an agent memory product. Its relevance is the executable-document design: Markdown prose, YAML-serialized request blocks, linked block/file reuse, runtime request traces, project sidecars, git/search integration, installable extensions, and composed Claude/Codex skills all sit close enough to normal files that humans, agents, and Git can inspect them.

Repository: https://github.com/VoidenHQ/voiden

Reviewed commit: 01fe83b039060ab69cfc3dc31e42c189fc7275ed

Last checked: 2026-05-16

Core Ideas

The source document is a hybrid Markdown/YAML executable file. A .void file is ordinary text with YAML frontmatter, Markdown documentation, and fenced void code blocks whose inner YAML serializes TipTap/ProseMirror node JSON (README.md, apps/electron/skills/base.skill.md). The serializer adds version/generated metadata, serializes known Markdown through prosemirror-markdown, and falls back to a void fence containing YAML for custom nodes; the parser strips frontmatter, parses Markdown with remark, and inflates void fences back into schema nodes (apps/ui/src/core/editors/voiden/markdownConverter.ts, apps/ui/src/core/file-system/hooks/useFileSystem.ts). Markdown paragraphs are knowledge artifacts when read as docs. Request, auth, body, assertion, script, variable-capture, and stitch blocks become system-definition artifacts when the runtime executes, mutates, validates, or routes requests from them.

TipTap is the editable form, but .void text is the storage substrate. Voiden's editor combines base Markdown/editor extensions with plugin-registered request nodes, linked-file nodes, source-sync indicators, search highlighting, table behavior, unique IDs, and keyboard behavior (apps/ui/src/core/editors/voiden/extensions.ts, apps/ui/src/core/editors/voiden/extensions/uniqueId.ts). The editor surface is a runtime view; the committed .void file is the canonical knowledge and system-definition artifact. That split matters for merge review: reviewers inspect YAML blocks and UIDs, while the app depends on schema-compatible TipTap deserialization.

Linked blocks and linked files make reusable request structure first-class. linkedBlock stores a target blockUid plus originalFile, fetches the target .void file, parses it, finds the block by UID, renders it read-only, and can inline it on unlink (apps/ui/src/core/editors/voiden/extensions/BlockLink.tsx). linkedFile imports a whole .void file or a section selected by request-separator UID (apps/ui/src/core/editors/voiden/extensions/LinkedFile.tsx). At execution time, the orchestrator expands linked blocks with forceRefresh: true and expands linked files before section splitting, so runtime behavior follows current disk content rather than a stale preview cache (apps/ui/src/core/editors/voiden/utils/expandLinkedBlocks.ts, apps/ui/src/core/request-engine/requestOrchestrator.ts). Imported blocks carry behavior-shaping authority because they can supply shared auth, headers, bodies, scripts, or assertions to future executions.

Reuse is dynamic enough to create collaboration and merge obligations. The source-sync plan documents an explicit choice against auto-refresh flicker: source blocks that have linked consumers get a ProseMirror decoration, and clicking it propagates changes by invalidating caches (docs/import-sync-plan.md). File moves and renames scan .void files and rewrite originalFile/filePath references inside void fences after user confirmation (apps/electron/src/main/fileSystem.ts). This is stronger than a markdown link convention, but weaker than a typed module system: UID stability, path rewrites, and linked-block conflicts remain collaborative review concerns.

The request runtime is a core pipeline with extension hooks. The architecture docs put the request engine in core and protocol/UI behavior in extensions (docs/architecture/OVERVIEW.md, docs/architecture/CORE_VS_EXTENSIONS.md). In code, requestOrchestrator lets plugins register build and response handlers, then sendRequestHybrid runs pre-processing, request compilation, pre-send, secure Electron request execution, post-processing, and runtime-variable capture (apps/ui/src/core/request-engine/requestOrchestrator.ts, apps/ui/src/core/request-engine/sendRequestHybrid.ts, apps/ui/src/core/request-engine/pipeline/HookRegistry.ts). Electron owns network execution, environment replacement, WebSocket/gRPC registries, and response extraction (apps/electron/src/main/ipc/request.ts). The runtime surface is therefore both editor-shaped and plugin-shaped: stored blocks define intent, extensions compile/execute it, and Electron supplies privileged effects.

Local sidecars are deliberately separate from source .void documents. Project identity and lock state live in .voiden/.voiden-projects (apps/electron/src/main/projectUtils.ts). Public/private environment YAML files live under .voiden/, with legacy .env fallback and profile discovery (apps/electron/src/main/env.ts). Captured runtime variables live in .voiden/.process.env.json, scoped by active environment (apps/electron/src/main/variables.ts, apps/ui/src/core/request-engine/runtimeVariables.ts). Gitignore support ignores .voiden/* while allowing public env YAMLs through (apps/electron/src/main/git.ts). These sidecars are system-definition artifacts when they configure environment replacement, variable capture, project lock behavior, or runtime state; most are intentionally not shared source artifacts.

Request and stitch histories are traces, not durable learning. Opt-in request history writes per-file JSON under .voiden/history, stores request/response metadata, caps response bodies, tracks multipart attachment hashes instead of file bytes, prunes by retention, and can export history entries back into .void files (apps/ui/src/core/history/historyManager.ts, apps/ui/src/core/history/types.ts, apps/ui/src/core/history/voidFileBuilder.ts, apps/ui/src/core/history/pipelineHooks.ts). Stitch runner stores run summaries under .voiden/stitch-runner/ and keeps the latest 20 entries per source file (core-extensions/src/voiden-stitch/lib/stitchHistory.ts). These are knowledge artifacts when used as evidence or replay material. They do not qualify as trace-derived learning at this commit because the code does not mine request histories or agent traces into durable rules, tests, templates, policies, skills, rankers, or model state.

Git and search are part of the workspace, not a sync service. Voiden uses simple-git for branch status, checkout, branch creation, diffs, commits, stash, conflict handling, remotes, push/pull, and tree decorations (apps/electron/src/preload/api/git.ts, apps/electron/src/main/git.ts, apps/electron/src/main/ipc/git.ts). Global text search streams rg --vimgrep results, skips .voiden and heavy binary/archive types, and has a JS fallback that extracts readable text from Markdown plus custom YAML blocks (apps/electron/src/main/ipc/search.ts). File-open search uses a bundled IntelliJ-style fuzzy matcher over rg --files output (apps/electron/src/main/ipc/files.ts, packages/fuzzy-search/src/index.ts). Search results are activation aids, not retained memory.

Extensions and agent skills are composable behavior packages. Core extensions are discovered from manifests into generated metadata and plugin maps, then loaded if enabled (core-extensions/src/registry.ts, core-extensions/src/plugins.ts, docs/extensions/AUTO_DISCOVERY.md). Community extensions are listed from VoidenHQ/plugins, installed from GitHub release assets or zip into the app's user-data extensions directory, and may include manifest.json, main.js, optional main-process.js, and optional skill.md (apps/electron/src/main/extension/extensionFetcher.ts, apps/electron/src/main/extension/extensionInstaller.ts, apps/electron/src/main/extension/extensionManager.ts, apps/electron/src/main/extensionLoader.ts). The skill composer concatenates the base .void skill plus enabled extension skill.md files and installs the result to ~/.claude/skills/voiden/SKILL.md and/or ~/.codex/skills/voiden/SKILL.md (apps/electron/src/main/skillsComposer.ts, apps/electron/src/main/skillsInstaller.ts). Those installed skills are system-definition artifacts for agents: they instruct how to create and edit .void files, but they are generated projections of enabled extensions, not canonical project content.

Comparison with Our System

Dimension Voiden Commonplace
Primary purpose API workspace with executable request documents Agent-operated KB methodology and artifact governance
Canonical substrate Git-trackable .void files plus selective public .voiden config Git-tracked typed Markdown collections, sources, indexes, instructions, reviews
Executability Request, assertion, script, runtime-variable, and stitch blocks execute through app/extension runtime Commands, validators, skills, review bundles, and scripts execute around the KB
Reuse model UID-addressed linked blocks and linked files imported into runtime execution Authored links, generated indexes, skills, and copied/promotion-based artifact reuse
Sidecars .voiden project/env/history/runtime files plus app userData state Generated indexes/reports under KB paths; volatile caches generally outside source
Collaboration Git UI, branch diff/conflict support, path rewrites for linked references Git discipline plus validation/review gates and type-level collection contracts
Agent support Generated Claude/Codex skill from enabled extension docs Skills and AGENTS instructions are part of the methodology substrate
Trace-derived learning Request/run history is stored and exportable, but not mined into durable behavior rules Trace-derived learning is a reviewed design axis with explicit promotion requirements

The strongest overlap is the file-as-runtime-object pattern. Voiden does not just store API documentation beside requests; the document itself is executable, reusable, searchable, diffable, and agent-editable. Commonplace makes notes, type specs, and instructions behavior-shaping through validation and agent consumption; Voiden makes request blocks behavior-shaping through an app runtime.

The main divergence is authority discipline. Voiden's block schemas are implicit in TipTap nodes and plugin handlers. Commonplace's artifact contracts are explicit type specs, collection conventions, and validators. Voiden is more ergonomic for API work because it can give each block a rich editor and immediate runtime. Commonplace is more reviewable for methodology because its symbolic contracts are documented as first-class KB artifacts.

Voiden also has a sharper source/sidecar split for runtime data. Source .void documents belong in Git. Request histories, runtime variables, private env, app state, installed extensions, autosaves, and logs live in ignored local directories. Commonplace can borrow that clarity: a file-backed system still needs local operational state, but the behavioral authority of that state must be named separately from the canonical library.

Read-back: both — agents can search and read executable .void files, while composed Claude/Codex skills load enabled-extension guidance into agent runtimes.

Borrowable Ideas

Executable document blocks. Commonplace should keep resisting hidden databases for canonical knowledge, but Voiden shows a strong middle path: store structured executable blocks as readable YAML inside Markdown. Ready as a pattern for future workflow/workshop artifacts, not for ordinary notes.

UID-based block reuse with execution-time refresh. Linked blocks are more precise than file-level transclusion and let shared auth/headers/scripts behave like modules. Commonplace could use this only where block identity affects execution; prose notes should not gain UID machinery without a concrete runtime need.

Sidecar taxonomy by authority. Voiden's .voiden directory separates project metadata, public/private env, runtime variables, request history, and stitch history. Commonplace should keep generated reports, caches, and runtime traces visibly distinct from canonical notes, and should decide which sidecars may become Git-tracked.

Agent skill composition from installed capabilities. Voiden's composed Claude/Codex skill is a practical projection: enabled extensions determine what agents need to know. Commonplace skills could similarly compile a project-local agent guide from installed type specs and promoted commands, if regeneration and source links are explicit.

Search that understands custom blocks without indexing everything. Voiden's global search strips frontmatter and extracts readable content from custom YAML nodes. A commonplace search layer should likewise parse typed blocks enough to find human-relevant text while skipping volatile or private sidecars.

Reference rewrites on file moves. Voiden scans .void files and offers to rewrite originalFile/filePath references after moves. Commonplace has link validation and relocation commands; a more general "move plus typed-reference rewrite" path is ready to borrow where references are structured.

Curiosity Pass

The .void format is plain text but not simple Markdown. It is merge-friendly compared with a binary/API-client database, but request blocks are serialized ProseMirror nodes. Humans and agents can edit them, yet a bad YAML shape or UID collision can break runtime behavior.

Linked reuse acts like imports without module boundaries. Execution-time expansion is useful and fresh, but a target block can silently alter many consumers. The source-sync indicator helps, but review still needs "who imports this?" visibility before changing shared auth, headers, scripts, or bodies.

History is intentionally low authority. Request history can be replayed or exported into .void files, and stitch history can show run outcomes. That is evidence and convenience, not learning. Promotion requires a user or future feature to turn a trace into a committed request, assertion, template, or skill.

Extension authority is split between shipped core, app userData, and generated agent skills. Core extensions are reviewable in the repo. Community extension code is installed locally from releases or zips. Agent skills are generated from enabled extensions. Those are three different storage substrates and three different review surfaces.

Git-native does not automatically make everything merge-safe. Git handles .void text, but sidecars are mostly ignored, linked-block paths can move, generated frontmatter changes timestamps, and runtime histories are local. The collaboration story is strongest for source .void documents and weaker for local operational context.

What to Watch

  • Whether Voiden adds a formal .void schema, formatter, or validator that can run outside the Electron app.
  • Whether linked-block consumers get a project-wide dependency graph, stale-reference checks, or merge-conflict-specific repair tools.
  • Whether request or stitch histories ever feed automatic assertion generation, template updates, skill updates, policy changes, or ranking, which would change the trace-derived learning classification.
  • Whether community extension sandboxing, signing, or permissioning becomes stronger as extension code gains access to request execution and agent skill generation.
  • Whether generated Claude/Codex skills include provenance back to the base skill and extension skill.md sources, so agents can distinguish canonical source from compiled guidance.
  • Whether public .voiden/env-*-public.yaml becomes a stable collaboration contract for teams or remains an app convenience around private local state.

Relevant Notes:

  • Knowledge artifact - classifies: Markdown docs, request histories, stitch histories, search results, and runtime traces when consumed as evidence or reference.
  • System-definition artifact - classifies: request blocks, scripts, assertions, env config, extension manifests, generated agent skills, and pipeline hooks when they configure or execute behavior.
  • Behavioral authority - frames: the same stored object can advise, configure, execute, rank, or instruct depending on consumer surface.
  • Storage substrate - distinguishes: source .void files, .voiden sidecars, app userData state, installed extensions, and agent skill install paths.
  • Lineage - frames: linked blocks, linked files, generated skills, histories, and exported .void files need source/dependency tracking to be safely reviewed.