Storage & PKM Integration

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

First time using AIWG? Begin with Install, Connect, and Verify. This guide assumes AIWG is already installed, `all` is deployed for your provider, and the agent-owned context regeneration procedure has connected the agent to this project.

By default AIWG persists everything under `.aiwg/` in your project. That's fine for most projects. But when you want AIWG memory to flow into your existing personal-knowledge system — Obsidian, Logseq, Fortemi — or you want to move heavy artifacts (research papers, media caches) onto a secondary drive, AIWG has a pluggable storage system that handles this with one config file.

This guide walks through the common moves.

---

When to set this up

Skip this if:

• You're new to AIWG and want to focus on the SDLC workflow first
• `.aiwg/` is fine where it lives (you're not running out of space, you don't use a separate PKM)

Set it up when:

• You already use Obsidian or Logseq daily and want AIWG memory in your graph
• You're acquiring a large research corpus and your project drive is filling up
• You're running multiple projects and want a single shared memory store

---

Five-minute setup: route AIWG memory into Obsidian

You have an Obsidian vault at `~/vaults/main` and want AIWG memory pages to land in `AIWG/memory/` inside it.

1. Create `.aiwg/storage.config`:

   {
     "version": "1",
     "backends": {
       "memory": {
         "type": "obsidian",
         "vault": "~/vaults/main",
         "folder": "AIWG/memory"
       }
     }
   }

2. Verify:

Use AIWG to complete this documented outcome: 2. Verify
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

3. (Optional) Move existing AIWG memory into the vault:

Use AIWG to complete this documented outcome: 3. (Optional) Move existing AIWG memory into the vault
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

That's it. Every memory write from AIWG now lands in your vault. Obsidian's file watcher picks up changes within seconds.

The same pattern works for `kb`, `reflections`, `provenance`, etc. — just change the subsystem key in `backends`.

---

Three-minute setup: relocate the research corpus to a different drive

You have a research corpus that's getting big. You want it on `/mnt/archive/` instead of taking space on the project drive.

1. Add a path override in `.aiwg/storage.config`:

   {
     "version": "1",
     "roots": {
       "research": "/mnt/archive/aiwg-research"
     }
   }

2. Migrate existing data:

Use AIWG to complete this documented outcome: 2. Migrate existing data
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

3. Verify:

Use AIWG to complete this documented outcome: 3. Verify
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

The research corpus now lives on the secondary drive. Same access pattern from AIWG; nothing else changes.

---

Subsystems you can route

Subsystem	What lives here	Default location
`memory`	Consumer-framework semantic memory (pages, lessons)	`.aiwg/memory/`
`reflections`	Agent-loop reflections	`.aiwg/reflections/`
`kb`	Knowledge-base pages	`.aiwg/kb/`
`activity_log`	Cross-framework event log	`.aiwg/activity.log`
`provenance`	W3C PROV records	`.aiwg/provenance/`
`research`	Research corpus	`.aiwg/research/`
`media`	Media artifacts	`.aiwg/media/`
`sandbox_identity`	Persistent agent identities	`~/.config/aiwg/sandbox-agents.json`

Each subsystem can be configured independently. Mix and match.

---

Backends available today

Backend	Status	Use case
`fs`	READY (default)	Local filesystem. Free, fast, no external deps
`obsidian`	READY	You already use Obsidian as your PKM
`logseq`	READY	You already use Logseq as your PKM
`fortemi`	READY (alpha)	First-party AIWG semantic-memory; Postgres + pgvector

Stub-tracked (planned, refuses with a clear error if configured today):

• `notion` (#959), `anythingllm` (#960), `s3` (#962), `webdav` (#963)

---

Security: tokens never go in storage.config

Every credential — API tokens, passwords, S3 keys — comes from environment variables, never from `.aiwg/storage.config`. The schema actively rejects credential-named properties at every nesting depth, and the agent-owned doctor operation does a recursive walk as defense-in-depth.

This means: it's safe to commit `.aiwg/storage.config` to git. It's NOT safe to put credentials in it.

See `docs/storage/security.md` for the full security model.

---

What to do next

• Configure another subsystem — repeat the five-minute setup with `kb`, `reflections`, etc.
• Read the per-backend page — `docs/storage/backends/<type>.md` covers env vars, caveats, and setup specifics.
• Migrate in chunks — the agent-owned storage operation resumes on retry, so you can run it incrementally on a large corpus.
• Verify with the doctor — the agent-owned doctor operation validates `storage.config` and probes each declared backend.

For the full reference, see `docs/storage/`.