Backend: `logseq`

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.

Routes a subsystem's persistence into a Logseq graph. AIWG writes Markdown files directly into the graph's filesystem; Logseq's file watcher picks up changes within seconds.

When to use

• You already use Logseq for daily journaling / PKM and want AIWG memory in your graph.
• You want AIWG entries to participate in Logseq's block-level linking, queries, and properties.

Configuration

{
  "version": "1",
  "backends": {
    "kb": {
      "type": "logseq",
      "graph": "~/.logseq/graphs/work",  // required
      "useApi": true,                     // optional, default true
      "apiUrl": "http://127.0.0.1:12315/api"  // optional
    }
  }
}

Field	Required	Notes
`graph`	yes	Absolute path to the graph directory
`useApi`	no	Default `true`. When true, probes the HTTP API on init
`apiUrl`	no	Default `http://127.0.0.1:12315/api`

Optional env var: `LOGSEQ_API_TOKEN` — only when `useApi: true`. Generate one in Logseq via Settings → Features → Developer mode.

How it works

The adapter does direct filesystem reads/writes against the graph root. Logseq's on-disk layout:

<graph>/
  pages/<title>.md          regular pages
  journals/YYYY_MM_DD.md    journal entries
  logseq/                   REFUSED (Logseq config)

When `useApi: true` (default), `init()` POSTs once to `<apiUrl>` with a `Bearer` token from `LOGSEQ_API_TOKEN` to confirm reachability. On missing token or unreachable API, emits a one-time stderr warning and continues with direct filesystem writes.

Frontmatter → property:: transform

Logseq doesn't recognize YAML frontmatter. The adapter strips any `---` YAML block from incoming content and renders the fields as Logseq page-level properties:

Input:

---
tags: [ai, note]
created: 2026-04-28
---
body

Written to disk:

tags:: ai, note
created:: 2026-04-28

body

`WriteMeta.frontmatter` (from `aiwg <subsystem> put` with the meta hint) merges over in-content YAML — the caller wins. Block IDs (`id::`) the caller smuggles in are stripped — Logseq auto-assigns them.

Capabilities

Operation	Notes
`read`	Returns `null` for missing files; refuses paths into `logseq/`
`write`	Strips YAML, emits `property::`, strips smuggled `id::` lines
`list`	Recursive walk; `logseq/` is skipped at the graph root
`delete`	No-op for missing; refuses `logseq/`
`query`	Not implemented in v1

Path safety

Same five rules as `fs` (`..`/absolute/`~`/backslash/empty), plus the `logseq/` config-dir refusal. Tested in `test/unit/storage/logseq.test.ts`.

Caveats

• DB version not yet supported. As of April 2025 Logseq's DB-backed rewrite is still in development; this adapter targets file-backed graphs. When the DB version stabilizes, the adapter behavior will need re-validation.
• API integration is conservative. `useApi: true` only probes reachability. AIWG doesn't yet synthesize HTTP API commands to write through the running app. Direct filesystem writes converge via Logseq's file watcher in seconds.
• Block IDs are auto-assigned. Don't write `id:: <uuid>` lines from AIWG — Logseq handles this. The adapter strips them defensively.
• `query` is not implemented. Use Logseq's native query DSL on the resulting pages.

Setup

1. Install Logseq and create or open a graph. 2. (Optional) Enable the HTTP API server: Settings → Features → Developer mode → enable the API token. 3. Export the API token: `export LOGSEQ_API_TOKEN=<token>` (only needed if `useApi: true`). 4. Add the backend to `.aiwg/storage.config`:

   {
     "version": "1",
     "backends": {
       "kb": {
         "type": "logseq",
         "graph": "~/.logseq/graphs/work"
       }
     }
   }

5. Verify:

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

6. (Optional) Migrate existing data into the graph:

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

See also

• `docs/storage/migration.md` — moving existing data into the graph
• Logseq docs: https://docs.logseq.com