Project Structure

After running swarmvault init, your workspace looks like this:

my-vault/
|-- swarmvault.config.json
|-- swarmvault.schema.md
|-- inbox/
|-- raw/
|   |-- sources/
|   `-- assets/
|-- wiki/
|   |-- index.md
|   |-- log.md
|   |-- candidates/
|   |-- graph/
|   |-- insights/
|   |-- context/
|   |-- exports/
|   |-- memory/
|   |-- sources/
|   |-- code/
|   |-- concepts/
|   |-- entities/
|   |-- projects/
|   `-- outputs/
|       |-- assets/
|       |-- chat-sessions/
|       `-- index.md
|-- state/
|   |-- manifests/
|   |-- extracts/
|   |-- analyses/
|   |-- code-index.json
|   |-- embeddings.json
|   |-- graph.json
|   |-- context-packs/
|   |-- chat-sessions/
|   |-- memory/
|   |-- retrieval/
|   |-- compile-state.json
|   |-- sessions/
|   |-- approvals/
|   |-- schedules/
|   `-- jobs.ndjson
|-- .obsidian/
`-- agent/

Key Directories

  • `swarmvault.schema.md` - vault-specific markdown instructions used by compile and query
  • `inbox/` - staging area for browser clips, imported markdown and HTML bundles, and other capture workflows
  • `raw/sources/` - immutable canonical copies of ingested source files
  • `raw/assets/` - copied sidecar assets referenced by inbox markdown bundles and localized remote URL images
  • `wiki/` - generated markdown pages for sources, code modules, concepts, entities, indexes, saved answers, and exploration hubs
  • `wiki/log.md` - append-only activity log for ingest, compile, query, lint, review, and candidate operations
  • `wiki/candidates/` - staged concept and entity pages awaiting confirmation on a later compile
  • `wiki/insights/` - human-authored pages that SwarmVault can read during compile and query but does not rewrite
  • `wiki/graph/` - graph orientation pages, including report.md, share-card.md, share-card.svg, share-kit/, report.json, and per-community summaries
  • `wiki/context/` - markdown companions for saved context packs
  • `wiki/exports/ai/` - default static AI export pack with llms.txt, full text, JSON-LD graph data, manifest metadata, and optional page siblings
  • `wiki/memory/` - task ledger index and markdown task pages
  • `wiki/code/` - module pages generated from ingested JavaScript, JSX, TypeScript, TSX, Bash, Python, Go, Rust, Java, Kotlin, Scala, Dart, Lua, Zig, C#, C, C++, PHP, Ruby, PowerShell, Elixir, OCaml, Objective-C, ReScript, Solidity, HTML, CSS, Vue, Svelte, Julia, Verilog/SystemVerilog, R, and SQL sources, with explicit diagnostics when a detected language lacks a safe packaged parser
  • `wiki/projects/` - project rollups over canonical pages when projects are configured
  • `wiki/outputs/assets/` - local chart/image artifacts plus JSON manifests for saved visual outputs
  • `wiki/outputs/chat-sessions/` - markdown transcripts for persisted swarmvault chat sessions
  • `state/manifests/` - source metadata, content hashes, storage locations, and attachment references
  • `state/extracts/` - extracted markdown plus JSON sidecars with extractor metadata, warnings, PDF page counts, Word family (.docx/.docm/.dotx/.dotm) metadata, RTF paragraph counts, OpenDocument metadata, EPUB chapter details, CSV/TSV and Excel family (.xlsx/.xlsm/.xlsb/.xls/.xltx/.xltm) tabular previews, PowerPoint family (.pptx/.pptm/.potx/.potm) slide metadata, Jupyter notebook cell/output counts, BibTeX/Org-mode/AsciiDoc structure, structured config/data schema hints, and image-vision details
  • `state/analyses/` - provider-generated analysis output
  • `state/code-index.json` - repo-aware code aliases, module names, namespaces/packages, and local import resolution data
  • `state/embeddings.json` - cached graph-semantic vectors used by swarmvault graph query and embedding-backed similarity enrichment
  • `state/context-packs/` - JSON context-pack artifacts with citations, token-budget accounting, included items, and omitted items
  • `state/chat-sessions/` - structured chat state used by swarmvault chat --resume
  • `state/memory/tasks/` - JSON task ledger records with decisions, linked context packs, changed paths, outcomes, and follow-ups

When SWARMVAULT_OUT=<dir> is set, generated artifact directories such as raw/, wiki/, state/, agent/, and inbox/ live under that output root. swarmvault.config.json and swarmvault.schema.md remain in the project root.

  • `state/benchmark.json` - latest graph-guided context benchmark summary
  • `state/compile-state.json` - incremental compile metadata, source hashes, root and project-effective schema hashes, source project assignments, saved-output hashes, and candidate history
  • `state/sessions/` - canonical session artifacts for compile, query, explore, lint, and watch
  • `state/approvals/` - staged review bundles produced by swarmvault compile --approve
  • `state/schedules/` - persisted state for configured schedule jobs
  • `state/watch/` - watch-status and pending semantic refresh artifacts for tracked repo automation
  • `state/jobs.ndjson` - automation run log written by swarmvault watch
  • `.git/hooks/` - optional local git hooks managed by swarmvault hook install when the vault lives inside a git repository
  • `.obsidian/` - optional Obsidian workspace files written by swarmvault init --obsidian
  • `agent/` - agent-specific files and future agent integrations

Main Artifacts

  • `state/graph.json` - compiled graph data
  • `state/retrieval/` - local retrieval index directory, including the SQLite FTS shard and manifest
  • `wiki/index.md` - entry point into the compiled markdown wiki
  • `wiki/log.md` - human-readable recent activity trail for the vault
  • `wiki/projects/index.md` - entry point into project-aware rollups
  • `wiki/outputs/index.md` - index of saved answers and exploration runs
  • `wiki/outputs/chat-sessions/<id>.md` / `state/chat-sessions/<id>.json` - persisted multi-turn conversations generated by swarmvault chat
  • `wiki/context/<id>.md` / `state/context-packs/<id>.json` - bounded agent context packs generated by swarmvault context build
  • `wiki/exports/ai/` - static AI handoff files generated by swarmvault export ai
  • `wiki/memory/tasks/<id>.md` / `state/memory/tasks/<id>.json` - durable task ledgers generated by swarmvault memory
  • `wiki/graph/share-card.md` / `wiki/graph/share-card.svg` / `wiki/graph/share-kit/` - compact post-ready text, visual graph summaries, and portable HTML-preview bundles generated by swarmvault graph share
  • Generated page frontmatter - lifecycle fields such as status, created_at, updated_at, compiled_from, managed_by, schema_hash, and project_ids, plus source_type on research-aware captures and source_class on repo-aware page outputs

Configuration File

swarmvault.config.json controls workspace paths, provider configuration, task routing, viewer settings, and installed agent types. swarmvault.schema.md controls vault-specific naming, categorization, and grounding behavior. See Configuration and Schema for details.