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 connected to the target project and your provider session can read the deployed context.

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.

---

Filesystem access boundary

The `fs` backend pins each configured subsystem root when its adapter is created. Existing external stores and root aliases remain supported. Missing configured roots are created on the first write or append through a pinned existing ancestor; a replacement installed at that missing root is refused. Missing reads return `null`, missing deletes are no-ops, and missing-root listings are empty.

Read, write, append, delete, and list share the artifact containment implementation. Absolute paths, parent traversal, escaping/dangling symlinks, unverifiable identities, and root replacement are refused. Linux allows contained read symlinks; writes, appends, and deletes refuse final symlinks. macOS and Windows refuse all symlink components. Storage refuses hardlinked files for read/write/append/delete; listing omits hardlinks and never emits or descends through symlinks. Deleting a directory is refused. Ordinary nested paths and `.aiwg-location` storage metadata remain supported, as do POSIX names ending in a dot or space.

Overwrites preserve file modes and use atomic replacement. Appends use `O_APPEND`; new files retain normal umask permissions. Linux anchors operations with directory descriptors; macOS and Windows perform static path and identity checks. Concurrent tree changes by the same user after final verification are outside this guarantee. Failed overwrites may leave private `0o600` `.aiwg-write-*.tmp` files.

---

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/`.