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.