Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

feat(companions): add optional OMC importer

AkitaOnRailsbc79a9c056fe
diff --git a/.gitignore b/.gitignore
index 971a38d4..a17aab5b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,6 @@
# Rust build artefacts.
/target/
+/companions/*/target/
/dist/
**/*.rs.bk
**/*.rs.orig
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8f43aad9..42ee3932 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Added
+- Added the standalone optional `companions/ai-memory-importer` package for
+ dry-run-by-default OMC flat Markdown wiki imports through public HTTP APIs;
+ it is isolated from the root Cargo workspace and root `cargo test --workspace`.
- Auto-improvement reviews can now stage bounded patch proposals for existing
`_rules/` and `procedures/` pages using append, add-section, and checked
replace-section edits, with base-body hashes guarding materialize-to-stage
diff --git a/README.md b/README.md
index 4572864e..582fe6c1 100644
--- a/README.md
+++ b/README.md
@@ -447,6 +447,15 @@ Useful entry points:
screenshots and e2e tests — lives at
[djalmajr/ai-memory-ui](https://github.com/djalmajr/ai-memory-ui).
+ Richer products such as import/migration pipelines and write-capable
+ browser chat/editors should live as optional companion crates or projects
+ that call ai-memory's public HTTP/MCP surfaces. The first implemented
+ companion is the standalone OMC wiki importer at
+ [`companions/ai-memory-importer`](companions/ai-memory-importer), which is
+ intentionally not a root workspace member and is not included in root
+ `cargo test --workspace`. See
+ [`docs/companion-crates.md`](docs/companion-crates.md) for the boundary.
+
When a reverse proxy hosts ai-memory under a URL subpath, set
`--base-path` (or `AI_MEMORY_BASE_PATH`) so every HTTP surface moves
together. Example: `--base-path /wiki` serves MCP at `/wiki/mcp`, hooks at
@@ -569,6 +578,7 @@ diagram, crate breakdown, schema notes, and invariants.
| [`docs/https-via-proxy.md`](docs/https-via-proxy.md) | **HTTPS via a reverse proxy.** When you need TLS (multi-user, non-loopback) and when you don't (loopback / stdio). Copy-paste docker compose templates for Caddy + Let's Encrypt, Caddy + internal CA (LAN-only), Cloudflare Tunnel (no open ports), and external cert files; plus native-Caddy + nginx recipes. The "thinking you're secure when you're not" failure modes explicitly called out. |
| [`docs/lifecycle-ops.md`](docs/lifecycle-ops.md) | **Read before running purge / rename / backup / restore / reset / reindex / restore-page.** Safety matrix for state-touching commands, per-project disk layout (how isolation actually works), checkpoint-based page recovery, and operator workflows for "fresh start", "snapshot before risky op", "drop one project", and rebuilding SQLite from wiki files. |
| [`docs/auto-improvement-loop.md`](docs/auto-improvement-loop.md) | Auto-improvement design notes: Hermes-inspired scheduled review, auto-approval default, manual review opt-in, pending proposal storage, and curator work. |
+| [`docs/companion-crates.md`](docs/companion-crates.md) | Boundary and implementation plan for optional companion projects, including the standalone importer at [`companions/ai-memory-importer`](companions/ai-memory-importer), without widening core ai-memory. |
| [`docs/llm-provider-comparison.md`](docs/llm-provider-comparison.md) | Empirical notes behind the recommended LLM defaults. |
| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Operational summary: data flow, crate layout, cross-cutting invariants, schema. |
| [`docs/design-decisions.md`](docs/design-decisions.md) | The full v1 spec. |
diff --git a/companions/ai-memory-importer/Cargo.lock b/companions/ai-memory-importer/Cargo.lock
new file mode 100644
index 00000000..f995ff01
--- /dev/null
+++ b/companions/ai-memory-importer/Cargo.lock
@@ -0,0 +1,1707 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "ai-memory-importer"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "clap",
+ "reqwest",
+ "serde",
+ "serde_json",
+ "serde_yaml",
+ "sha2",
+ "tempfile",
+ "tokio",
+ "url",
+ "walkdir",
+]
+
+[[package]]
+name = "anstream"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "824a212faf96e9acacdbd09febd34438f8f711fb84e09a8916013cd7815ca28d"
+dependencies = [
+ "anstyle",
+ "anstyle-parse",
+ "anstyle-query",
+ "anstyle-wincon",
+ "colorchoice",
+ "is_terminal_polyfill",
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle"
+version = "1.0.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
+
+[[package]]
+name = "anstyle-parse"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52ce7f38b242319f7cabaa6813055467063ecdc9d355bbb4ce0c68908cd8130e"
+dependencies = [
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle-query"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "anstyle-wincon"
+version = "3.0.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
+dependencies = [
+ "anstyle",
+ "once_cell_polyfill",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "anyhow"
+version = "1.0.102"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
+
+[[package]]
+name = "atomic-waker"
+version = "1.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0"
+
+[[package]]
+name = "base64"
+version = "0.22.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
+
+[[package]]
+name = "bitflags"
+version = "2.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4388bee8683e3d04af747c73422af53102d2bd24d9eadb6cbc100baef4b43f8"
+
+[[package]]
+name = "block-buffer"
+version = "0.10.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
+dependencies = [
+ "generic-array",
+]
+
+[[package]]
+name = "bumpalo"
+version = "3.20.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
+
+[[package]]
+name = "bytes"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ae3f5d315924270530207e2a68396c3cc547f6dca3fbdca317cfb1a51edb593"
+
+[[package]]
+name = "cc"
+version = "1.2.65"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e228eec9be7c17ccb640b59b36a5cd805ea2a564a4c5e162c2f659fea30d3b96"
+dependencies = [
+ "find-msvc-tools",
+ "shlex",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "cfg_aliases"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "613afe47fcd5fac7ccf1db93babcb082c5994d996f20b8b159f2ad1658eb5724"
+
+[[package]]
+name = "clap"
+version = "4.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ddb117e43bbf7dacf0a4190fef4d345b9bad68dfc649cb349e7d17d28428e51"
+dependencies = [
+ "clap_builder",
+ "clap_derive",
+]
+
+[[package]]
+name = "clap_builder"
+version = "4.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "714a53001bf66416adb0e2ef5ac857140e7dc3a0c48fb28b2f10762fc4b5069f"
+dependencies = [
+ "anstream",
+ "anstyle",
+ "clap_lex",
+ "strsim",
+]
+
+[[package]]
+name = "clap_derive"
+version = "4.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2ce8604710f6733aa641a2b3731eaa1e8b3d9973d5e3565da11800813f997a9"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "clap_lex"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
+
+[[package]]
+name = "colorchoice"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
+
+[[package]]
+name = "cpufeatures"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "crypto-common"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
+dependencies = [
+ "generic-array",
+ "typenum",
+]
+
+[[package]]
+name = "digest"
+version = "0.10.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
+dependencies = [
+ "block-buffer",
+ "crypto-common",
+]
+
+[[package]]
+name = "displaydoc"
+version = "0.2.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ac70aa55017e108007fbaf5aa0f54b021c98f92ff8af59d42eda9da96e3dd4f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "equivalent"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
+
+[[package]]
+name = "errno"
+version = "0.3.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
+dependencies = [
+ "libc",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "fastrand"
+version = "2.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6"
+
+[[package]]
+name = "find-msvc-tools"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
+
+[[package]]
+name = "form_urlencoded"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf"
+dependencies = [
+ "percent-encoding",
+]
+
+[[package]]
+name = "futures-channel"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "07bbe89c50d7a535e539b8c17bc0b49bdb77747034daa8087407d655f3f7cc1d"
+dependencies = [
+ "futures-core",
+]
+
+[[package]]
+name = "futures-core"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7e3450815272ef58cec6d564423f6e755e25379b217b0bc688e295ba24df6b1d"
+
+[[package]]
+name = "futures-task"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "037711b3d59c33004d3856fbdc83b99d4ff37a24768fa1be9ce3538a1cde4393"
+
+[[package]]
+name = "futures-util"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "389ca41296e6190b48053de0321d02a77f32f8a5d2461dd38762c0593805c6d6"
+dependencies = [
+ "futures-core",
+ "futures-task",
+ "pin-project-lite",
+ "slab",
+]
+
+[[package]]
+name = "generic-array"
+version = "0.14.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
+dependencies = [
+ "typenum",
+ "version_check",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
+dependencies = [
+ "cfg-if",
+ "js-sys",
+ "libc",
+ "wasi",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
+dependencies = [
+ "cfg-if",
+ "js-sys",
+ "libc",
+ "r-efi 5.3.0",
+ "wasip2",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "r-efi 6.0.0",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.17.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "http"
+version = "1.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6970f50e31d6fc17d3fa27329444bfa74e196cf62e95052a3f6fee181dba6425"
+dependencies = [
+ "bytes",
+ "itoa",
+]
+
+[[package]]
+name = "http-body"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1efedce1fb8e6913f23e0c92de8e62cd5b772a67e7b3946df930a62566c93184"
+dependencies = [
+ "bytes",
+ "http",
+]
+
+[[package]]
+name = "http-body-util"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b021d93e26becf5dc7e1b75b1bed1fd93124b374ceb73f43d4d4eafec896a64a"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "http",
+ "http-body",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "httparse"
+version = "1.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"
+
+[[package]]
+name = "hyper"
+version = "1.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "55281c53a1894c864990125767da440a4e630446785086f52523b20033b74498"
+dependencies = [
+ "atomic-waker",
+ "bytes",
+ "futures-channel",
+ "futures-core",
+ "http",
+ "http-body",
+ "httparse",
+ "itoa",
+ "pin-project-lite",
+ "smallvec",
+ "tokio",
+ "want",
+]
+
+[[package]]
+name = "hyper-rustls"
+version = "0.27.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "33ca68d021ef39cf6463ab54c1d0f5daf03377b70561305bb89a8f83aab66e0f"
+dependencies = [
+ "http",
+ "hyper",
+ "hyper-util",
+ "rustls",
+ "tokio",
+ "tokio-rustls",
+ "tower-service",
+ "webpki-roots",
+]
+
+[[package]]
+name = "hyper-util"
+version = "0.1.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "96547c2556ec9d12fb1578c4eaf448b04993e7fb79cbaad930a656880a6bdfa0"
+dependencies = [
+ "base64",
+ "bytes",
+ "futures-channel",
+ "futures-util",
+ "http",
+ "http-body",
+ "hyper",
+ "ipnet",
+ "libc",
+ "percent-encoding",
+ "pin-project-lite",
+ "socket2",
+ "tokio",
+ "tower-service",
+ "tracing",
+]
+
+[[package]]
+name = "icu_collections"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2984d1cd16c883d7935b9e07e44071dca8d917fd52ecc02c04d5fa0b5a3f191c"
+dependencies = [
+ "displaydoc",
+ "potential_utf",
+ "utf8_iter",
+ "yoke",
+ "zerofrom",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_locale_core"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92219b62b3e2b4d88ac5119f8904c10f8f61bf7e95b640d25ba3075e6cac2c29"
+dependencies = [
+ "displaydoc",
+ "litemap",
+ "tinystr",
+ "writeable",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_normalizer"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c56e5ee99d6e3d33bd91c5d85458b6005a22140021cc324cea84dd0e72cff3b4"
+dependencies = [
+ "icu_collections",
+ "icu_normalizer_data",
+ "icu_properties",
+ "icu_provider",
+ "smallvec",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_normalizer_data"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da3be0ae77ea334f4da67c12f149704f19f81d1adf7c51cf482943e84a2bad38"
+
+[[package]]
+name = "icu_properties"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bee3b67d0ea5c2cca5003417989af8996f8604e34fb9ddf96208a033901e70de"
+dependencies = [
+ "icu_collections",
+ "icu_locale_core",
+ "icu_properties_data",
+ "icu_provider",
+ "zerotrie",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_properties_data"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e2bbb201e0c04f7b4b3e14382af113e17ba4f63e2c9d2ee626b720cbce54a14"
+
+[[package]]
+name = "icu_provider"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "139c4cf31c8b5f33d7e199446eff9c1e02decfc2f0eec2c8d71f65befa45b421"
+dependencies = [
+ "displaydoc",
+ "icu_locale_core",
+ "writeable",
+ "yoke",
+ "zerofrom",
+ "zerotrie",
+ "zerovec",
+]
+
+[[package]]
+name = "idna"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de"
+dependencies = [
+ "idna_adapter",
+ "smallvec",
+ "utf8_iter",
+]
+
+[[package]]
+name = "idna_adapter"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb68373c0d6620ef8105e855e7745e18b0d00d3bdb07fb532e434244cdb9a714"
+dependencies = [
+ "icu_normalizer",
+ "icu_properties",
+]
+
+[[package]]
+name = "indexmap"
+version = "2.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
+dependencies = [
+ "equivalent",
+ "hashbrown",
+]
+
+[[package]]
+name = "ipnet"
+version = "2.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d98f6fed1fde3f8c21bc40a1abb88dd75e67924f9cffc3ef95607bad8017f8e2"
+
+[[package]]
+name = "is_terminal_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "js-sys"
+version = "0.3.102"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "03d04c30968dffe80775bd4d7fb676131cd04a1fb46d2686dbffbaec2d9dfd31"
+dependencies = [
+ "cfg-if",
+ "futures-util",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.186"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
+
+[[package]]
+name = "linux-raw-sys"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
+
+[[package]]
+name = "litemap"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92daf443525c4cce67b150400bc2316076100ce0b3686209eb8cf3c31612e6f0"
+
+[[package]]
+name = "log"
+version = "0.4.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
+
+[[package]]
+name = "lru-slab"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "112b39cec0b298b6c1999fee3e31427f74f676e4cb9879ed1a121b43661a4154"
+
+[[package]]
+name = "memchr"
+version = "2.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "88904434abc2901f197fe8cc55f0445e7ded921dba5911dad2e2b39b48e663c4"
+
+[[package]]
+name = "mio"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "02bd0af71c67b473010cbbc60715ee815645a4dc942899111f494b4b737d6fda"
+dependencies = [
+ "libc",
+ "wasi",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "once_cell_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
+
+[[package]]
+name = "percent-encoding"
+version = "2.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
+
+[[package]]
+name = "pin-project-lite"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
+
+[[package]]
+name = "potential_utf"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0103b1cef7ec0cf76490e969665504990193874ea05c85ff9bab8b911d0a0564"
+dependencies = [
+ "zerovec",
+]
+
+[[package]]
+name = "ppv-lite86"
+version = "0.2.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9"
+dependencies = [
+ "zerocopy",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quinn"
+version = "0.11.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c1a41e437b6bbd489372cd4971de128e85c855f56c57f283d20ff016cf7c0a8"
+dependencies = [
+ "bytes",
+ "cfg_aliases",
+ "pin-project-lite",
+ "quinn-proto",
+ "quinn-udp",
+ "rustc-hash",
+ "rustls",
+ "socket2",
+ "thiserror",
+ "tokio",
+ "tracing",
+ "web-time",
+]
+
+[[package]]
+name = "quinn-proto"
+version = "0.11.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4fcb935c5bec503c2f0e306bdd3e58bb9029dcb14fa8d9ac76e3a5256ac0763e"
+dependencies = [
+ "bytes",
+ "getrandom 0.3.4",
+ "lru-slab",
+ "rand",
+ "ring",
+ "rustc-hash",
+ "rustls",
+ "rustls-pki-types",
+ "slab",
+ "thiserror",
+ "tinyvec",
+ "tracing",
+ "web-time",
+]
+
+[[package]]
+name = "quinn-udp"
+version = "0.5.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "addec6a0dcad8a8d96a771f815f0eaf55f9d1805756410b39f5fa81332574cbd"
+dependencies = [
+ "cfg_aliases",
+ "libc",
+ "once_cell",
+ "socket2",
+ "tracing",
+ "windows-sys 0.60.2",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "r-efi"
+version = "5.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
+
+[[package]]
+name = "r-efi"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
+
+[[package]]
+name = "rand"
+version = "0.9.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "44c5af06bb1b7d3216d91932aed5265164bf384dc89cd6ba05cf59a35f5f76ea"
+dependencies = [
+ "rand_chacha",
+ "rand_core",
+]
+
+[[package]]
+name = "rand_chacha"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb"
+dependencies = [
+ "ppv-lite86",
+ "rand_core",
+]
+
+[[package]]
+name = "rand_core"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "76afc826de14238e6e8c374ddcc1fa19e374fd8dd986b0d2af0d02377261d83c"
+dependencies = [
+ "getrandom 0.3.4",
+]
+
+[[package]]
+name = "reqwest"
+version = "0.12.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eddd3ca559203180a307f12d114c268abf583f59b03cb906fd0b3ff8646c1147"
+dependencies = [
+ "base64",
+ "bytes",
+ "futures-core",
+ "http",
+ "http-body",
+ "http-body-util",
+ "hyper",
+ "hyper-rustls",
+ "hyper-util",
+ "js-sys",
+ "log",
+ "percent-encoding",
+ "pin-project-lite",
+ "quinn",
+ "rustls",
+ "rustls-pki-types",
+ "serde",
+ "serde_json",
+ "serde_urlencoded",
+ "sync_wrapper",
+ "tokio",
+ "tokio-rustls",
+ "tower",
+ "tower-http",
+ "tower-service",
+ "url",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "web-sys",
+ "webpki-roots",
+]
+
+[[package]]
+name = "ring"
+version = "0.17.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a4689e6c2294d81e88dc6261c768b63bc4fcdb852be6d1352498b114f61383b7"
+dependencies = [
+ "cc",
+ "cfg-if",
+ "getrandom 0.2.17",
+ "libc",
+ "untrusted",
+ "windows-sys 0.52.0",
+]
+
+[[package]]
+name = "rustc-hash"
+version = "2.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94300abf3f1ae2e2b8ffb7b58043de3d399c73fa6f4b73826402a5c457614dbe"
+
+[[package]]
+name = "rustix"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190"
+dependencies = [
+ "bitflags",
+ "errno",
+ "libc",
+ "linux-raw-sys",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "rustls"
+version = "0.23.41"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6b92b125634d9b795e7beca796cc790df15a7fb38323bf3196fda83292d06b1f"
+dependencies = [
+ "once_cell",
+ "ring",
+ "rustls-pki-types",
+ "rustls-webpki",
+ "subtle",
+ "zeroize",
+]
+
+[[package]]
+name = "rustls-pki-types"
+version = "1.14.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "30a7197ae7eb376e574fe940d068c30fe0462554a3ddbe4eca7838e049c937a9"
+dependencies = [
+ "web-time",
+ "zeroize",
+]
+
+[[package]]
+name = "rustls-webpki"
+version = "0.103.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61c429a8649f110dddef65e2a5ad240f747e85f7758a6bccc7e5777bd33f756e"
+dependencies = [
+ "ring",
+ "rustls-pki-types",
+ "untrusted",
+]
+
+[[package]]
+name = "rustversion"
+version = "1.0.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
+
+[[package]]
+name = "ryu"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"
+
+[[package]]
+name = "same-file"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502"
+dependencies = [
+ "winapi-util",
+]
+
+[[package]]
+name = "serde"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.150"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "serde_urlencoded"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3491c14715ca2294c4d6a88f15e84739788c1d030eed8c110436aafdaa2f3fd"
+dependencies = [
+ "form_urlencoded",
+ "itoa",
+ "ryu",
+ "serde",
+]
+
+[[package]]
+name = "serde_yaml"
+version = "0.9.34+deprecated"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6a8b1a1a2ebf674015cc02edccce75287f1a0130d394307b36743c2f5d504b47"
+dependencies = [
+ "indexmap",
+ "itoa",
+ "ryu",
+ "serde",
+ "unsafe-libyaml",
+]
+
+[[package]]
+name = "sha2"
+version = "0.10.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
+dependencies = [
+ "cfg-if",
+ "cpufeatures",
+ "digest",
+]
+
+[[package]]
+name = "shlex"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
+
+[[package]]
+name = "slab"
+version = "0.4.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
+
+[[package]]
+name = "smallvec"
+version = "1.15.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90"
+
+[[package]]
+name = "socket2"
+version = "0.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52d1cfed4120b4d927bf7c0f86d2087a4a7d6027c906d9f9d525a80573b9be51"
+dependencies = [
+ "libc",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "stable_deref_trait"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
+
+[[package]]
+name = "strsim"
+version = "0.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
+
+[[package]]
+name = "subtle"
+version = "2.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
+
+[[package]]
+name = "syn"
+version = "2.0.118"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "sync_wrapper"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0bf256ce5efdfa370213c1dabab5935a12e49f2c58d15e9eac2870d3b4f27263"
+dependencies = [
+ "futures-core",
+]
+
+[[package]]
+name = "synstructure"
+version = "0.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "728a70f3dbaf5bab7f0c4b1ac8d7ae5ea60a4b5549c8a5914361c99147a709d2"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "tempfile"
+version = "3.27.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
+dependencies = [
+ "fastrand",
+ "getrandom 0.4.3",
+ "once_cell",
+ "rustix",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "thiserror"
+version = "2.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4288b5bcbc7920c07a1149a35cf9590a2aa808e0bc1eafaade0b80947865fbc4"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "2.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ebc4ee7f67670e9b64d05fa4253e753e016c6c95ff35b89b7941d6b856dec1d5"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "tinystr"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8323304221c2a851516f22236c5722a72eaa19749016521d6dff0824447d96d"
+dependencies = [
+ "displaydoc",
+ "zerovec",
+]
+
+[[package]]
+name = "tinyvec"
+version = "1.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3e61e67053d25a4e82c844e8424039d9745781b3fc4f32b8d55ed50f5f667ef3"
+dependencies = [
+ "tinyvec_macros",
+]
+
+[[package]]
+name = "tinyvec_macros"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
+
+[[package]]
+name = "tokio"
+version = "1.52.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fc7f01b389ac15039e4dc9531aa973a135d7a4135281b12d7c1bc79fd57fffe"
+dependencies = [
+ "bytes",
+ "libc",
+ "mio",
+ "pin-project-lite",
+ "socket2",
+ "tokio-macros",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "tokio-macros"
+version = "2.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "385a6cb71ab9ab790c5fe8d67f1645e6c450a7ce006a33de03daa956cf70a496"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "tokio-rustls"
+version = "0.26.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1729aa945f29d91ba541258c8df89027d5792d85a8841fb65e8bf0f4ede4ef61"
+dependencies = [
+ "rustls",
+ "tokio",
+]
+
+[[package]]
+name = "tower"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ebe5ef63511595f1344e2d5cfa636d973292adc0eec1f0ad45fae9f0851ab1d4"
+dependencies = [
+ "futures-core",
+ "futures-util",
+ "pin-project-lite",
+ "sync_wrapper",
+ "tokio",
+ "tower-layer",
+ "tower-service",
+]
+
+[[package]]
+name = "tower-http"
+version = "0.6.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4cfcf7e2740e6fc6d4d688b4ef00650406bb94adf4731e43c096c3a19fe40840"
+dependencies = [
+ "bitflags",
+ "bytes",
+ "futures-util",
+ "http",
+ "http-body",
+ "pin-project-lite",
+ "tower",
+ "tower-layer",
+ "tower-service",
+ "url",
+]
+
+[[package]]
+name = "tower-layer"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "121c2a6cda46980bb0fcd1647ffaf6cd3fc79a013de288782836f6df9c48780e"
+
+[[package]]
+name = "tower-service"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8df9b6e13f2d32c91b9bd719c00d1958837bc7dec474d94952798cc8e69eeec3"
+
+[[package]]
+name = "tracing"
+version = "0.1.44"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
+dependencies = [
+ "pin-project-lite",
+ "tracing-core",
+]
+
+[[package]]
+name = "tracing-core"
+version = "0.1.36"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
+dependencies = [
+ "once_cell",
+]
+
+[[package]]
+name = "try-lock"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
+
+[[package]]
+name = "typenum"
+version = "1.20.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "unsafe-libyaml"
+version = "0.2.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "673aac59facbab8a9007c7f6108d11f63b603f7cabff99fabf650fea5c32b861"
+
+[[package]]
+name = "untrusted"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1"
+
+[[package]]
+name = "url"
+version = "2.5.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed"
+dependencies = [
+ "form_urlencoded",
+ "idna",
+ "percent-encoding",
+ "serde",
+]
+
+[[package]]
+name = "utf8_iter"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
+
+[[package]]
+name = "utf8parse"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
+
+[[package]]
+name = "version_check"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
+
+[[package]]
+name = "walkdir"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29790946404f91d9c5d06f9874efddea1dc06c5efe94541a7d6863108e3a5e4b"
+dependencies = [
+ "same-file",
+ "winapi-util",
+]
+
+[[package]]
+name = "want"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bfa7760aed19e106de2c7c0b581b509f2f25d3dacaf737cb82ac61bc6d760b0e"
+dependencies = [
+ "try-lock",
+]
+
+[[package]]
+name = "wasi"
+version = "0.11.1+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
+
+[[package]]
+name = "wasip2"
+version = "1.0.4+wasi-0.2.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487"
+dependencies = [
+ "wit-bindgen",
+]
+
+[[package]]
+name = "wasm-bindgen"
+version = "0.2.125"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ddb3f79143bced6de84270411622a2699cee572fc0875aeaf1e7867cf9fca1a"
+dependencies = [
+ "cfg-if",
+ "once_cell",
+ "rustversion",
+ "wasm-bindgen-macro",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-futures"
+version = "0.4.75"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "503b14d284f2c8dac03b819967e155ea753f573586193b2b2c95990cb5d69280"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "wasm-bindgen-macro"
+version = "0.2.125"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4e21a184b13fb19e157296e2c46056aec9092264fab83e4ba59e68c61b323c3d"
+dependencies = [
+ "quote",
+ "wasm-bindgen-macro-support",
+]
+
+[[package]]
+name = "wasm-bindgen-macro-support"
+version = "0.2.125"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fecefd9c35bd935a20fc3fc344b5f29138961e4f47fb03297d88f2587afb5ebd"
+dependencies = [
+ "bumpalo",
+ "proc-macro2",
+ "quote",
+ "syn",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-shared"
+version = "0.2.125"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23939e44bb9a5d7576fa2b563dc2e136628f1224e88a8deed09e04858b77871f"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "web-sys"
+version = "0.3.102"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6430a72df5eb332242960fe84b3002a241163998241eb596d4f739b9757061d"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "web-time"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a6580f308b1fad9207618087a65c04e7a10bc77e02c8e84e9b00dd4b12fa0bb"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "webpki-roots"
+version = "1.0.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bf85cb06032201fa7c6f829d7db5a7e5aa45bcc0655327713065f6f0576731bf"
+dependencies = [
+ "rustls-pki-types",
+]
+
+[[package]]
+name = "winapi-util"
+version = "0.1.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-sys"
+version = "0.52.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
+dependencies = [
+ "windows-targets 0.52.6",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.60.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2f500e4d28234f72040990ec9d39e3a6b950f9f22d3dba18416c35882612bcb"
+dependencies = [
+ "windows-targets 0.53.5",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows-targets"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
+dependencies = [
+ "windows_aarch64_gnullvm 0.52.6",
+ "windows_aarch64_msvc 0.52.6",
+ "windows_i686_gnu 0.52.6",
+ "windows_i686_gnullvm 0.52.6",
+ "windows_i686_msvc 0.52.6",
+ "windows_x86_64_gnu 0.52.6",
+ "windows_x86_64_gnullvm 0.52.6",
+ "windows_x86_64_msvc 0.52.6",
+]
+
+[[package]]
+name = "windows-targets"
+version = "0.53.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4945f9f551b88e0d65f3db0bc25c33b8acea4d9e41163edf90dcd0b19f9069f3"
+dependencies = [
+ "windows-link",
+ "windows_aarch64_gnullvm 0.53.1",
+ "windows_aarch64_msvc 0.53.1",
+ "windows_i686_gnu 0.53.1",
+ "windows_i686_gnullvm 0.53.1",
+ "windows_i686_msvc 0.53.1",
+ "windows_x86_64_gnu 0.53.1",
+ "windows_x86_64_gnullvm 0.53.1",
+ "windows_x86_64_msvc 0.53.1",
+]
+
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
+
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a9d8416fa8b42f5c947f8482c43e7d89e73a173cead56d044f6a56104a6d1b53"
+
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
+
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9d782e804c2f632e395708e99a94275910eb9100b2114651e04744e9b125006"
+
+[[package]]
+name = "windows_i686_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
+
+[[package]]
+name = "windows_i686_gnu"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "960e6da069d81e09becb0ca57a65220ddff016ff2d6af6a223cf372a506593a3"
+
+[[package]]
+name = "windows_i686_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
+
+[[package]]
+name = "windows_i686_gnullvm"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fa7359d10048f68ab8b09fa71c3daccfb0e9b559aed648a8f95469c27057180c"
+
+[[package]]
+name = "windows_i686_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
+
+[[package]]
+name = "windows_i686_msvc"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e7ac75179f18232fe9c285163565a57ef8d3c89254a30685b57d83a38d326c2"
+
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
+
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9c3842cdd74a865a8066ab39c8a7a473c0778a3f29370b5fd6b4b9aa7df4a499"
+
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
+
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ffa179e2d07eee8ad8f57493436566c7cc30ac536a3379fdf008f47f6bb7ae1"
+
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
+
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6bbff5f0aada427a1e5a6da5f1f98158182f26556f345ac9e04d36d0ebed650"
+
+[[package]]
+name = "wit-bindgen"
+version = "0.57.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e"
+
+[[package]]
+name = "writeable"
+version = "0.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ffae5123b2d3fc086436f8834ae3ab053a283cfac8fe0a0b8eaae044768a4c4"
+
+[[package]]
+name = "yoke"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "709fe23a0424b6a435d82152b1bd3fdfb0833487d5fa90d05d42762a9891fef5"
+dependencies = [
+ "stable_deref_trait",
+ "yoke-derive",
+ "zerofrom",
+]
+
+[[package]]
+name = "yoke-derive"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "de844c262c8848816172cef550288e7dc6c7b7814b4ee56b3e1553f275f1858e"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+ "synstructure",
+]
+
+[[package]]
+name = "zerocopy"
+version = "0.8.52"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce1022995ff5ff5d841ad7d994facc23098cd40152f2c1d11cd607c6f530653f"
+dependencies = [
+ "zerocopy-derive",
+]
+
+[[package]]
+name = "zerocopy-derive"
+version = "0.8.52"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ae7f38b72ec2a254e2b87ef277cf2cd4fb97cbebf944faa6f33354da0867930"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "zerofrom"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272"
+dependencies = [
+ "zerofrom-derive",
+]
+
+[[package]]
+name = "zerofrom-derive"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11532158c46691caf0f2593ea8358fed6bbf68a0315e80aae9bd41fbade684a1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+ "synstructure",
+]
+
+[[package]]
+name = "zeroize"
+version = "1.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e13c156562582aa81c60cb29407084cdb54c4164760106ab78e6c5b0858cf64e"
+
+[[package]]
+name = "zerotrie"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0f9152d31db0792fa83f70fb2f83148effb5c1f5b8c7686c3459e361d9bc20bf"
+dependencies = [
+ "displaydoc",
+ "yoke",
+ "zerofrom",
+]
+
+[[package]]
+name = "zerovec"
+version = "0.11.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "90f911cbc359ab6af17377d242225f4d75119aec87ea711a880987b18cd7b239"
+dependencies = [
+ "yoke",
+ "zerofrom",
+ "zerovec-derive",
+]
+
+[[package]]
+name = "zerovec-derive"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "625dc425cab0dca6dc3c3319506e6593dcb08a9f387ea3b284dbd52a92c40555"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "zmij"
+version = "1.0.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
diff --git a/companions/ai-memory-importer/Cargo.toml b/companions/ai-memory-importer/Cargo.toml
new file mode 100644
index 00000000..dc36cd5d
--- /dev/null
+++ b/companions/ai-memory-importer/Cargo.toml
@@ -0,0 +1,22 @@
+[workspace]
+
+[package]
+name = "ai-memory-importer"
+version = "0.1.0"
+edition = "2024"
+publish = false
+
+[dependencies]
+anyhow = "1"
+clap = { version = "4", features = ["derive", "env"] }
+reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+serde_yaml = "0.9"
+sha2 = "0.10"
+tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
+url = "2"
+walkdir = "2"
+
+[dev-dependencies]
+tempfile = "3"
diff --git a/companions/ai-memory-importer/README.md b/companions/ai-memory-importer/README.md
new file mode 100644
index 00000000..a853984f
--- /dev/null
+++ b/companions/ai-memory-importer/README.md
@@ -0,0 +1,102 @@
+# ai-memory-importer
+
+Standalone optional companion for importing external memory corpora into a
+running ai-memory server. This crate is deliberately isolated from the root
+workspace: its `Cargo.toml` has its own `[workspace]`, uses only crates.io
+dependencies, and is not included in root `cargo test --workspace`.
+
+## Supported source: OMC wiki directory
+
+The first importer supports oh-my-claudecode / OMC flat Markdown wiki
+directories. It reads only top-level `*.md` files, skips `index.md` and
+`session-log-*` by default, and writes deterministic destination paths under
+`omc/<slug>.md`.
+
+Claude memory graph and Qdrant imports are roadmap items only; there are no code
+stubs for them in v1.
+
+## Safety contract
+
+- Default mode is dry-run; live mode requires `--apply`.
+- Live mode requires explicit `--workspace`, `--project`, and
+ `--manifest-out <path>`.
+- Live writes use only `POST /admin/write-page`; the importer never opens
+ ai-memory SQLite or wiki files directly and never deletes pages.
+- The destination workspace/project must already exist unless
+ `--create-destination` is passed.
+- Existing destination pages abort the import unless `--overwrite` is passed.
+ The importer also re-checks each page immediately before writing.
+ This is best-effort protection: a concurrent writer could still race between
+ the check and `/admin/write-page`, so avoid running competing import/write jobs
+ into the same destination.
+- It stops on the first live-write error and updates the manifest with completed
+ writes and the failed checkpoint.
+- Path handling fails closed: absolute paths, `..`, unsafe destination paths,
+ and reserved/internal destination prefixes are rejected. Duplicate generated
+ destination paths abort planning.
+- Dry-run output does not print full page bodies unless `--show-body` is passed.
+- Only endpoint-supported metadata is mapped: `title`, `kind`, `tier`, `tags`,
+ `pinned`, and `body`. Unknown frontmatter is ignored.
+- Auth comes only from `AI_MEMORY_AUTH_TOKEN`; there is intentionally no CLI
+ token argument.
+
+## Usage
+
+Dry-run with a summary:
+
+```bash
+cargo run --manifest-path companions/ai-memory-importer/Cargo.toml -- \
+ omc-wiki --dir /path/to/omc/wiki --workspace default --project my-project
+```
+
+Dry-run with a manifest:
+
+```bash
+cargo run --manifest-path companions/ai-memory-importer/Cargo.toml -- \
+ omc-wiki --dir /path/to/omc/wiki --workspace default --project my-project \
+ --manifest-out /tmp/omc-import-manifest.json
+```
+
+Live import:
+
+```bash
+AI_MEMORY_AUTH_TOKEN=... \
+cargo run --manifest-path companions/ai-memory-importer/Cargo.toml -- \
+ omc-wiki --dir /path/to/omc/wiki --workspace default --project my-project \
+ --apply --manifest-out /tmp/omc-import-manifest.json
+```
+
+Options:
+
+- `--server-url URL`: ai-memory server URL; defaults to
+ `http://127.0.0.1:49374`, or `AI_MEMORY_SERVER_URL` when set. A URL path is
+ treated as the base path.
+- `--create-destination`: allow `/admin/write-page` to auto-create the
+ workspace/project after the read preflight fails.
+- `--overwrite`: replace existing destination pages.
+- `--include-session-logs`: include `session-log-*` pages.
+- `--show-body`: print full page bodies during dry-run.
+- `--pinned`: pin all imported pages.
+
+## Validation
+
+Run these from the repository root:
+
+```bash
+cargo fmt --check --manifest-path companions/ai-memory-importer/Cargo.toml
+cargo test --manifest-path companions/ai-memory-importer/Cargo.toml
+cargo clippy --manifest-path companions/ai-memory-importer/Cargo.toml --all-targets -- -D warnings
+```
+
+Root hygiene checks remain separate:
+
+```bash
+cargo fmt --check
+git diff --check
+```
+
+## Roadmap
+
+- Claude Code memory graph export import.
+- Qdrant collection import with user-supplied schema mapping.
+- Optional deterministic normalization passes after OMC import is stable.
diff --git a/companions/ai-memory-importer/src/main.rs b/companions/ai-memory-importer/src/main.rs
new file mode 100644
index 00000000..e74393e2
--- /dev/null
+++ b/companions/ai-memory-importer/src/main.rs
@@ -0,0 +1,803 @@
+use std::collections::HashMap;
+use std::fs;
+use std::path::{Component, Path, PathBuf};
+use std::time::Duration;
+
+use anyhow::{Context, Result, anyhow, bail};
+use clap::{Parser, Subcommand};
+use reqwest::StatusCode;
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+use url::Url;
+use walkdir::WalkDir;
+
+const IMPORT_VERSION: &str = "omc-wiki-v1";
+const DEFAULT_SERVER_URL: &str = "http://127.0.0.1:49374";
+
+#[derive(Parser, Debug)]
+#[command(author, version, about = "Optional ai-memory import companion")]
+struct Cli {
+ #[command(subcommand)]
+ command: Commands,
+}
+
+#[derive(Subcommand, Debug)]
+enum Commands {
+ /// Import an oh-my-claudecode / OMC flat markdown wiki directory.
+ OmcWiki(OmcArgs),
+}
+
+#[derive(Parser, Debug, Clone)]
+struct OmcArgs {
+ #[arg(long)]
+ dir: PathBuf,
+ #[arg(long)]
+ workspace: Option<String>,
+ #[arg(long)]
+ project: Option<String>,
+ #[arg(long, env = "AI_MEMORY_SERVER_URL", default_value = DEFAULT_SERVER_URL)]
+ server_url: String,
+ #[arg(long)]
+ apply: bool,
+ #[arg(long)]
+ manifest_out: Option<PathBuf>,
+ #[arg(long)]
+ create_destination: bool,
+ #[arg(long)]
+ overwrite: bool,
+ #[arg(long)]
+ include_session_logs: bool,
+ #[arg(long)]
+ show_body: bool,
+ #[arg(long)]
+ pinned: bool,
+}
+
+#[derive(Debug, Clone)]
+struct PlannedPage {
+ source_path: String,
+ source_sha256: String,
+ destination_path: String,
+ request: WritePageRequest,
+}
+
+#[derive(Debug, Serialize, Clone)]
+struct ManifestEntry {
+ import_version: String,
+ source_path: String,
+ source_sha256: String,
+ destination_path: String,
+ status: ManifestStatus,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ page_id: Option<String>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ path: Option<String>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ checkpoint: Option<String>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ error: Option<String>,
+}
+
+#[derive(Debug, Serialize, Clone, PartialEq, Eq)]
+#[serde(rename_all = "kebab-case")]
+enum ManifestStatus {
+ Planned,
+ Written,
+ Failed,
+}
+
+#[derive(Debug, Serialize, Clone)]
+struct Manifest {
+ import_version: String,
+ entries: Vec<ManifestEntry>,
+}
+
+#[derive(Debug, Serialize, Clone, PartialEq, Eq)]
+struct WritePageRequest {
+ workspace: String,
+ project: String,
+ path: String,
+ body: String,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ title: Option<String>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ kind: Option<String>,
+ tier: String,
+ tags: Vec<String>,
+ pinned: bool,
+}
+
+#[derive(Debug, Deserialize)]
+struct WritePageResponse {
+ page_id: String,
+ path: String,
+ checkpoint: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+struct PageListItem {
+ path: String,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(untagged)]
+enum PageListBody {
+ Bare(Vec<PageListItem>),
+ Wrapped { pages: Vec<PageListItem> },
+}
+
+impl PageListBody {
+ fn into_pages(self) -> Vec<PageListItem> {
+ match self {
+ Self::Bare(pages) | Self::Wrapped { pages } => pages,
+ }
+ }
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+ match Cli::parse().command {
+ Commands::OmcWiki(args) => run_omc(args).await,
+ }
+}
+
+async fn run_omc(args: OmcArgs) -> Result<()> {
+ if args.apply {
+ if args
+ .workspace
+ .as_deref()
+ .is_none_or(|s| s.trim().is_empty())
+ || args.project.as_deref().is_none_or(|s| s.trim().is_empty())
+ {
+ bail!("--apply requires explicit --workspace and --project");
+ }
+ if args.manifest_out.is_none() {
+ bail!("--apply requires --manifest-out <path>");
+ }
+ }
+ let workspace = args
+ .workspace
+ .clone()
+ .unwrap_or_else(|| "DRY-RUN-WORKSPACE".into());
+ let project = args
+ .project
+ .clone()
+ .unwrap_or_else(|| "DRY-RUN-PROJECT".into());
+ let planned = plan_omc_wiki(
+ &args.dir,
+ &workspace,
+ &project,
+ args.include_session_logs,
+ args.pinned,
+ )?;
+ let mut entries: Vec<_> = planned.iter().map(planned_entry).collect();
+
+ if !args.apply {
+ if args.show_body {
+ for page in &planned {
+ println!(
+ "--- {} -> {} ---\n{}",
+ page.source_path, page.destination_path, page.request.body
+ );
+ }
+ }
+ if let Some(path) = &args.manifest_out {
+ write_manifest(path, &entries)?;
+ } else {
+ println!(
+ "dry-run: planned {} writes; no HTTP writes performed",
+ planned.len()
+ );
+ for page in &planned {
+ println!("{} -> {}", page.source_path, page.destination_path);
+ }
+ }
+ return Ok(());
+ }
+
+ let manifest_path = args.manifest_out.as_ref().unwrap();
+ write_manifest(manifest_path, &entries)?;
+
+ let client = ImportClient::new(&args.server_url)?;
+ let destination_exists = client
+ .preflight_project(&workspace, &project, args.create_destination)
+ .await?;
+ if !args.overwrite && destination_exists {
+ let existing = client.existing_paths(&workspace, &project).await?;
+ let conflicts: Vec<_> = planned
+ .iter()
+ .filter(|p| existing.contains_key(&p.destination_path))
+ .collect();
+ if !conflicts.is_empty() {
+ bail!(
+ "destination already has {} planned path(s); rerun with --overwrite to replace",
+ conflicts.len()
+ );
+ }
+ }
+
+ for (idx, page) in planned.iter().enumerate() {
+ if !args.overwrite
+ && client
+ .page_exists(&workspace, &project, &page.destination_path)
+ .await?
+ {
+ entries[idx].status = ManifestStatus::Failed;
+ entries[idx].error = Some("destination page appeared before write; aborting".into());
+ write_manifest(manifest_path, &entries)?;
+ bail!(
+ "destination page appeared before write {}; completed {} writes",
+ page.destination_path,
+ idx
+ );
+ }
+ match client.write_page(&page.request).await {
+ Ok(resp) => {
+ entries[idx].status = ManifestStatus::Written;
+ entries[idx].page_id = Some(resp.page_id);
+ entries[idx].path = Some(resp.path);
+ entries[idx].checkpoint = resp.checkpoint;
+ write_manifest(manifest_path, &entries)?;
+ }
+ Err(err) => {
+ entries[idx].status = ManifestStatus::Failed;
+ entries[idx].error = Some(err.to_string());
+ write_manifest(manifest_path, &entries)?;
+ bail!("live write failed after {} completed writes: {err}", idx);
+ }
+ }
+ }
+ println!(
+ "import complete: wrote {} pages",
+ entries
+ .iter()
+ .filter(|e| e.status == ManifestStatus::Written)
+ .count()
+ );
+ Ok(())
+}
+
+fn planned_entry(page: &PlannedPage) -> ManifestEntry {
+ ManifestEntry {
+ import_version: IMPORT_VERSION.into(),
+ source_path: page.source_path.clone(),
+ source_sha256: page.source_sha256.clone(),
+ destination_path: page.destination_path.clone(),
+ status: ManifestStatus::Planned,
+ page_id: None,
+ path: None,
+ checkpoint: None,
+ error: None,
+ }
+}
+
+fn write_manifest(path: &Path, entries: &[ManifestEntry]) -> Result<()> {
+ let manifest = Manifest {
+ import_version: IMPORT_VERSION.into(),
+ entries: entries.to_vec(),
+ };
+ atomic_write(path, serde_json::to_string_pretty(&manifest)?.as_bytes())
+ .with_context(|| format!("write manifest {}", path.display()))
+}
+
+fn atomic_write(path: &Path, bytes: &[u8]) -> Result<()> {
+ if let Some(parent) = path.parent()
+ && !parent.as_os_str().is_empty()
+ && !parent.exists()
+ {
+ bail!(
+ "manifest parent directory does not exist: {}",
+ parent.display()
+ );
+ }
+ let tmp = temp_path_for(path)?;
+ fs::write(&tmp, bytes)?;
+ match fs::rename(&tmp, path) {
+ Ok(()) => Ok(()),
+ Err(err) => {
+ let _ = fs::remove_file(&tmp);
+ Err(err.into())
+ }
+ }
+}
+
+fn temp_path_for(path: &Path) -> Result<PathBuf> {
+ let file_name = path
+ .file_name()
+ .and_then(|s| s.to_str())
+ .ok_or_else(|| anyhow!("manifest path must include a file name"))?;
+ Ok(path.with_file_name(format!(".{file_name}.tmp")))
+}
+
+fn plan_omc_wiki(
+ dir: &Path,
+ workspace: &str,
+ project: &str,
+ include_session_logs: bool,
+ pinned: bool,
+) -> Result<Vec<PlannedPage>> {
+ let root =
+ fs::canonicalize(dir).with_context(|| format!("read source dir {}", dir.display()))?;
+ if !root.is_dir() {
+ bail!("--dir must be a directory");
+ }
+ let mut planned = Vec::new();
+ let mut destinations: HashMap<String, String> = HashMap::new();
+ for entry in WalkDir::new(&root)
+ .min_depth(1)
+ .max_depth(1)
+ .sort_by_file_name()
+ {
+ let entry = entry?;
+ if !entry.file_type().is_file() {
+ continue;
+ }
+ let path = entry.path();
+ if path.extension().and_then(|s| s.to_str()) != Some("md") {
+ continue;
+ }
+ let rel = path
+ .strip_prefix(&root)?
+ .to_string_lossy()
+ .replace('\\', "/");
+ validate_source_rel(&rel)?;
+ let name = path
+ .file_name()
+ .and_then(|s| s.to_str())
+ .ok_or_else(|| anyhow!("invalid filename"))?;
+ if name == "index.md" || (!include_session_logs && name.starts_with("session-log-")) {
+ continue;
+ }
+ let content =
+ fs::read_to_string(path).with_context(|| format!("read {}", path.display()))?;
+ let source_sha256 = sha256_hex(content.as_bytes());
+ let parsed = parse_markdown(&content)?;
+ let stem = path
+ .file_stem()
+ .and_then(|s| s.to_str())
+ .ok_or_else(|| anyhow!("invalid filename"))?;
+ let dest = format!("omc/{}.md", slugify(stem));
+ validate_destination_path(&dest)?;
+ if let Some(other) = destinations.insert(dest.clone(), rel.clone()) {
+ bail!("duplicate destination path collision: {other} and {rel} both map to {dest}");
+ }
+ planned.push(PlannedPage {
+ source_path: rel,
+ source_sha256,
+ destination_path: dest.clone(),
+ request: WritePageRequest {
+ workspace: workspace.to_owned(),
+ project: project.to_owned(),
+ path: dest,
+ body: parsed.body,
+ title: parsed.title,
+ kind: parsed.kind,
+ tier: normalize_tier(parsed.tier.as_deref())?,
+ tags: parsed.tags,
+ pinned: parsed.pinned || pinned,
+ },
+ });
+ }
+ Ok(planned)
+}
+
+fn normalize_tier(tier: Option<&str>) -> Result<String> {
+ let tier = tier.unwrap_or("semantic").trim();
+ match tier {
+ "working" | "episodic" | "semantic" | "procedural" => Ok(tier.to_owned()),
+ other => bail!("unsupported tier '{other}'"),
+ }
+}
+
+#[derive(Default)]
+struct ParsedMarkdown {
+ body: String,
+ title: Option<String>,
+ kind: Option<String>,
+ tier: Option<String>,
+ tags: Vec<String>,
+ pinned: bool,
+}
+
+fn parse_markdown(input: &str) -> Result<ParsedMarkdown> {
+ let mut out = ParsedMarkdown::default();
+ let body = if let Some(rest) = input.strip_prefix("---\n") {
+ if let Some(end) = rest.find("\n---\n") {
+ let yaml = &rest[..end];
+ let value: serde_yaml::Value =
+ serde_yaml::from_str(yaml).context("parse YAML frontmatter")?;
+ if let Some(map) = value.as_mapping() {
+ out.title = yaml_string(map, "title");
+ out.kind = yaml_string(map, "kind");
+ out.tier = yaml_string(map, "tier");
+ out.pinned = yaml_bool(map, "pinned").unwrap_or(false);
+ out.tags = yaml_tags(map);
+ }
+ rest[end + "\n---\n".len()..].to_owned()
+ } else {
+ input.to_owned()
+ }
+ } else {
+ input.to_owned()
+ };
+ if out.title.is_none() {
+ out.title = first_h1(&body);
+ }
+ out.body = body;
+ Ok(out)
+}
+
+fn yaml_key(key: &str) -> serde_yaml::Value {
+ serde_yaml::Value::String(key.into())
+}
+fn yaml_string(map: &serde_yaml::Mapping, key: &str) -> Option<String> {
+ map.get(yaml_key(key))
+ .and_then(|v| v.as_str())
+ .map(str::to_owned)
+ .filter(|s| !s.trim().is_empty())
+}
+fn yaml_bool(map: &serde_yaml::Mapping, key: &str) -> Option<bool> {
+ map.get(yaml_key(key)).and_then(|v| v.as_bool())
+}
+fn yaml_tags(map: &serde_yaml::Mapping) -> Vec<String> {
+ match map.get(yaml_key("tags")) {
+ Some(serde_yaml::Value::Sequence(seq)) => seq
+ .iter()
+ .filter_map(|v| v.as_str().map(str::to_owned))
+ .collect(),
+ Some(v) => v.as_str().map(|s| vec![s.to_owned()]).unwrap_or_default(),
+ None => Vec::new(),
+ }
+}
+fn first_h1(body: &str) -> Option<String> {
+ body.lines()
+ .find_map(|l| l.strip_prefix("# ").map(str::trim).map(str::to_owned))
+ .filter(|s| !s.is_empty())
+}
+
+fn validate_source_rel(rel: &str) -> Result<()> {
+ let p = Path::new(rel);
+ if p.is_absolute() || p.components().any(|c| matches!(c, Component::ParentDir)) {
+ bail!("unsafe source relative path: {rel}");
+ }
+ Ok(())
+}
+
+fn validate_destination_path(path: &str) -> Result<()> {
+ let p = Path::new(path);
+ if p.is_absolute()
+ || path.starts_with('/')
+ || path.contains('\\')
+ || p.components().any(|c| {
+ matches!(
+ c,
+ Component::ParentDir | Component::RootDir | Component::Prefix(_)
+ )
+ })
+ {
+ bail!("unsafe destination path: {path}");
+ }
+ let first = path.split('/').next().unwrap_or_default();
+ if matches!(
+ first,
+ "_rules"
+ | "_internal"
+ | ".git"
+ | "sessions"
+ | "session-logs"
+ | "procedures"
+ | "decisions"
+ | "gotchas"
+ ) {
+ bail!("reserved destination prefix: {first}");
+ }
+ if !path.ends_with(".md") {
+ bail!("destination path must end in .md");
+ }
+ Ok(())
+}
+
+fn slugify(s: &str) -> String {
+ let mut out = String::new();
+ let mut dash = false;
+ for ch in s.chars().flat_map(char::to_lowercase) {
+ if ch.is_ascii_alphanumeric() {
+ out.push(ch);
+ dash = false;
+ } else if !dash {
+ out.push('-');
+ dash = true;
+ }
+ }
+ let trimmed = out.trim_matches('-').to_string();
+ if trimmed.is_empty() {
+ "page".into()
+ } else {
+ trimmed
+ }
+}
+
+fn sha256_hex(bytes: &[u8]) -> String {
+ let digest = Sha256::digest(bytes);
+ digest.iter().map(|b| format!("{b:02x}")).collect()
+}
+
+struct ImportClient {
+ client: reqwest::Client,
+ origin: String,
+ base_path: String,
+ token: Option<String>,
+}
+
+impl ImportClient {
+ fn new(server_url: &str) -> Result<Self> {
+ let url = Url::parse(server_url).context("invalid --server-url")?;
+ let origin = format!(
+ "{}://{}",
+ url.scheme(),
+ url.host_str()
+ .ok_or_else(|| anyhow!("server URL needs host"))?
+ );
+ let origin = if let Some(port) = url.port() {
+ format!("{origin}:{port}")
+ } else {
+ origin
+ };
+ let base_path = url.path().trim_end_matches('/').to_owned();
+ let base_path = if base_path == "/" {
+ String::new()
+ } else {
+ base_path
+ };
+ Ok(Self {
+ client: reqwest::Client::builder()
+ .timeout(Duration::from_secs(30))
+ .build()?,
+ origin,
+ base_path,
+ token: std::env::var("AI_MEMORY_AUTH_TOKEN")
+ .ok()
+ .filter(|s| !s.is_empty()),
+ })
+ }
+ fn url(&self, path: &str) -> String {
+ format!("{}{}{}", self.origin, self.base_path, path)
+ }
+ fn request(&self, method: reqwest::Method, path: &str) -> reqwest::RequestBuilder {
+ let req = self.client.request(method, self.url(path));
+ if let Some(token) = &self.token {
+ req.bearer_auth(token)
+ } else {
+ req
+ }
+ }
+ async fn preflight_project(
+ &self,
+ workspace: &str,
+ project: &str,
+ create: bool,
+ ) -> Result<bool> {
+ let resp = self
+ .request(
+ reqwest::Method::GET,
+ &format!(
+ "/api/v1/workspaces/{}/projects/{}/pages",
+ enc(workspace),
+ enc(project)
+ ),
+ )
+ .send()
+ .await?;
+ if resp.status().is_success() {
+ Ok(true)
+ } else if resp.status() == StatusCode::NOT_FOUND && create {
+ Ok(false)
+ } else {
+ bail!(
+ "destination workspace/project must already exist (or pass --create-destination): HTTP {}",
+ resp.status()
+ )
+ }
+ }
+ async fn existing_paths(&self, workspace: &str, project: &str) -> Result<HashMap<String, ()>> {
+ let resp = self
+ .request(
+ reqwest::Method::GET,
+ &format!(
+ "/api/v1/workspaces/{}/projects/{}/pages",
+ enc(workspace),
+ enc(project)
+ ),
+ )
+ .send()
+ .await?;
+ if !resp.status().is_success() {
+ bail!("list destination pages failed: HTTP {}", resp.status());
+ }
+ let pages: PageListBody = resp.json().await?;
+ Ok(pages
+ .into_pages()
+ .into_iter()
+ .map(|page| (page.path, ()))
+ .collect())
+ }
+ async fn page_exists(&self, workspace: &str, project: &str, path: &str) -> Result<bool> {
+ let resp = self
+ .request(
+ reqwest::Method::GET,
+ &format!(
+ "/api/v1/workspaces/{}/projects/{}/pages/{}",
+ enc(workspace),
+ enc(project),
+ enc_path(path)
+ ),
+ )
+ .send()
+ .await?;
+ match resp.status() {
+ StatusCode::OK => Ok(true),
+ StatusCode::NOT_FOUND => Ok(false),
+ s => bail!("page pre-write check failed: HTTP {s}"),
+ }
+ }
+ async fn write_page(&self, req: &WritePageRequest) -> Result<WritePageResponse> {
+ let resp = self
+ .request(reqwest::Method::POST, "/admin/write-page")
+ .json(req)
+ .send()
+ .await?;
+ if !resp.status().is_success() {
+ bail!("write-page failed: HTTP {}", resp.status());
+ }
+ Ok(resp.json().await?)
+ }
+}
+
+fn enc(s: &str) -> String {
+ url::form_urlencoded::byte_serialize(s.as_bytes()).collect()
+}
+fn enc_path(s: &str) -> String {
+ s.split('/').map(enc).collect::<Vec<_>>().join("/")
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use tempfile::tempdir;
+
+ fn write(dir: &Path, name: &str, body: &str) {
+ fs::write(dir.join(name), body).unwrap();
+ }
+
+ #[test]
+ fn parses_omc_frontmatter() {
+ let parsed = parse_markdown("---\ntitle: T\nkind: rule\ntier: procedural\ntags: [a, b]\npinned: true\nextra: ignored\n---\n# Body\ntext").unwrap();
+ assert_eq!(parsed.title.as_deref(), Some("T"));
+ assert_eq!(parsed.kind.as_deref(), Some("rule"));
+ assert_eq!(parsed.tier.as_deref(), Some("procedural"));
+ assert_eq!(parsed.tags, vec!["a", "b"]);
+ assert!(parsed.pinned);
+ assert_eq!(parsed.body, "# Body\ntext");
+ }
+
+ #[test]
+ fn planning_rejects_unknown_tier_before_live_write() {
+ let td = tempdir().unwrap();
+ write(td.path(), "note.md", "---\ntier: legendary\n---\n# Note");
+ assert!(
+ plan_omc_wiki(td.path(), "w", "p", false, false)
+ .unwrap_err()
+ .to_string()
+ .contains("unsupported tier")
+ );
+ }
+
+ #[test]
+ fn skips_index_and_session_logs_by_default() {
+ let td = tempdir().unwrap();
+ write(td.path(), "index.md", "# Index");
+ write(td.path(), "session-log-1.md", "# Log");
+ write(td.path(), "note.md", "# Note");
+ let pages = plan_omc_wiki(td.path(), "w", "p", false, false).unwrap();
+ assert_eq!(pages.len(), 1);
+ assert_eq!(pages[0].destination_path, "omc/note.md");
+ }
+
+ #[test]
+ fn path_traversal_rejected() {
+ assert!(validate_source_rel("../x.md").is_err());
+ assert!(validate_destination_path("omc/../x.md").is_err());
+ assert!(validate_destination_path("/omc/x.md").is_err());
+ }
+
+ #[test]
+ fn detects_duplicate_slug_collisions() {
+ let td = tempdir().unwrap();
+ write(td.path(), "A B.md", "# A");
+ write(td.path(), "a-b.md", "# B");
+ assert!(
+ plan_omc_wiki(td.path(), "w", "p", false, false)
+ .unwrap_err()
+ .to_string()
+ .contains("collision")
+ );
+ }
+
+ #[test]
+ fn dry_run_planning_has_no_http_client() {
+ let td = tempdir().unwrap();
+ write(td.path(), "note.md", "# Note");
+ let pages = plan_omc_wiki(td.path(), "w", "p", false, false).unwrap();
+ assert_eq!(pages.len(), 1);
+ assert_eq!(pages[0].request.workspace, "w");
+ }
+
+ #[test]
+ fn write_request_json_shape() {
+ let req = WritePageRequest {
+ workspace: "w".into(),
+ project: "p".into(),
+ path: "omc/n.md".into(),
+ body: "# N".into(),
+ title: Some("N".into()),
+ kind: Some("fact".into()),
+ tier: "semantic".into(),
+ tags: vec!["omc".into()],
+ pinned: true,
+ };
+ let v = serde_json::to_value(req).unwrap();
+ assert_eq!(v["workspace"], "w");
+ assert_eq!(v["project"], "p");
+ assert_eq!(v["path"], "omc/n.md");
+ assert_eq!(v["body"], "# N");
+ assert_eq!(v["pinned"], true);
+ }
+
+ #[test]
+ fn parses_current_bare_api_page_list_shape() {
+ let body = r#"[{"path":"omc/a.md"},{"path":"notes/b.md"}]"#;
+ let parsed: PageListBody = serde_json::from_str(body).unwrap();
+ let paths: Vec<_> = parsed.into_pages().into_iter().map(|p| p.path).collect();
+ assert_eq!(paths, vec!["omc/a.md", "notes/b.md"]);
+ }
+
+ #[test]
+ fn parses_legacy_wrapped_api_page_list_shape() {
+ let body = r#"{"pages":[{"path":"omc/a.md"},{"path":"notes/b.md"}]}"#;
+ let parsed: PageListBody = serde_json::from_str(body).unwrap();
+ let paths: Vec<_> = parsed.into_pages().into_iter().map(|p| p.path).collect();
+ assert_eq!(paths, vec!["omc/a.md", "notes/b.md"]);
+ }
+
+ #[test]
+ fn auth_header_uses_bearer_scheme() {
+ let rb = reqwest::Client::new()
+ .get("http://127.0.0.1/")
+ .bearer_auth("secret-token");
+ let req = rb.build().unwrap();
+ assert_eq!(
+ req.headers().get(reqwest::header::AUTHORIZATION).unwrap(),
+ "Bearer secret-token"
+ );
+ let dbg = format!("{:?}", req.headers());
+ assert!(!dbg.contains("AI_MEMORY_AUTH_TOKEN"));
+ }
+
+ #[test]
+ fn overwrite_requires_explicit_flag() {
+ let args = OmcArgs {
+ dir: PathBuf::from("."),
+ workspace: Some("w".into()),
+ project: Some("p".into()),
+ server_url: DEFAULT_SERVER_URL.into(),
+ apply: true,
+ manifest_out: Some(PathBuf::from("m.json")),
+ create_destination: false,
+ overwrite: false,
+ include_session_logs: false,
+ show_body: false,
+ pinned: false,
+ };
+ assert!(!args.overwrite);
+ }
+}
diff --git a/docs/companion-crates.md b/docs/companion-crates.md
new file mode 100644
index 00000000..1649786c
--- /dev/null
+++ b/docs/companion-crates.md
@@ -0,0 +1,280 @@
+# Optional companion crates and projects
+
+This page records the boundary for feature ideas that are useful around
+ai-memory, but should not become core ai-memory surface area. PR #118 and PR
+#123 are the historical motivation: both are valid product ideas, but both patch
+too much import, chat, UI, and mutation behavior into the core server. The better
+shape is optional companion software that orchestrates ai-memory through public
+APIs.
+
+ai-memory stays a memory substrate:
+
+- one server binary owns hooks, MCP, the markdown wiki, SQLite indexes, auth,
+ admission webhooks, and the built-in read-only browser;
+- the wiki remains markdown-in-git as source of truth;
+- SQLite remains a derived index;
+- writes go through the existing wiki mutation path, admin endpoints, or MCP
+ tools;
+- the built-in `/web` and `/api/v1` surfaces stay read-oriented.
+
+Companion crates can be richer products. They should integrate through public
+HTTP/MCP surfaces instead of patching handlers, routes, or command surfaces into
+the core workspace.
+
+## Integration rules for companions
+
+Companion projects may:
+
+- call the read-only `/api/v1` endpoints for workspaces, projects, pages,
+ search, graph, recent pages, and briefing/overview snapshots;
+- call existing MCP tools such as `memory_write_page`, `memory_delete_page`,
+ `memory_read_page`, and `memory_query` when running as an agent/client;
+- call existing admin endpoints such as `/admin/write-page` and
+ `/admin/delete-page` when running as an operator-side server process with an
+ appropriate bearer token;
+- use `--web-ui-dir` to let ai-memory serve an alternate static SPA, as long as
+ the SPA still uses public HTTP APIs and does not require in-process plugins;
+- run their own LLM prompts, import transforms, queues, confirmation flows,
+ UI state, and project-specific policies;
+- ship their own CLI binary, web server, Docker image, tests, release cadence,
+ and docs.
+
+Companion projects should not:
+
+- become Cargo workspace members of core ai-memory by default;
+- add core MCP tools, admin endpoints, or CLI subcommands unless a missing seam
+ is independently useful to ai-memory itself;
+- write wiki files or SQLite rows directly;
+- bypass `AuthLevel::authorize`, admission webhooks, actor attribution, scope
+ resolution, or the single-writer store boundary;
+- require ai-memory to host arbitrary plugin code in-process.
+
+Companion features should be treated as separate products, not rejected ideas.
+They can move faster than core, have their own UX, and carry source-specific or
+workflow-specific behavior without widening ai-memory's default install.
+
+If a companion exposes browser writes, it must implement its own server-side
+mutation broker. Browsers should talk to the companion; the companion should talk
+to ai-memory with an operator token. That keeps CSRF, confirmation, audit, rate
+limits, and UI-specific policy outside the core server.
+
+## `ai-memory-importer`: migration and ingestion companion
+
+This is the companion shape for PR #118. The first implemented companion lives
+at [`companions/ai-memory-importer`](../companions/ai-memory-importer) as a
+standalone Cargo package with its own `[workspace]`; it is not a member of the
+root workspace and is not covered by root `cargo test --workspace`.
+
+### Goal
+
+Import or normalize existing memory corpora without making ai-memory core own
+every source format and migration workflow.
+
+Initial source support is intentionally narrow:
+
+- oh-my-claudecode / OMC flat markdown wiki directories.
+
+Future sources can include:
+
+- Claude Code memory graph exports such as `memory.jsonl` from
+ `@modelcontextprotocol/server-memory`;
+- Qdrant-backed memory collections, when a user supplies a collection URL and
+ schema mapping;
+- future one-off importers maintained on the companion's release cadence.
+
+### Validation
+
+Run companion checks explicitly from the repository root:
+
+```bash
+cargo fmt --check --manifest-path companions/ai-memory-importer/Cargo.toml
+cargo test --manifest-path companions/ai-memory-importer/Cargo.toml
+cargo clippy --manifest-path companions/ai-memory-importer/Cargo.toml --all-targets -- -D warnings
+```
+
+Root hygiene checks remain separate:
+
+```bash
+cargo fmt --check
+git diff --check
+```
+
+### Product shape
+
+Prefer a separate repository and binary crate, for example:
+
+```text
+companions/ai-memory-importer/
+├── Cargo.toml
+├── src/main.rs
+└── README.md
+```
+
+It can share Rust libraries later only if those libraries are published with a
+stable API and are useful outside ai-memory. It should not need to be a member of
+this workspace.
+
+### How it talks to ai-memory
+
+Read and plan:
+
+- use `/api/v1/workspaces`, `/api/v1/projects`, `/api/v1/pages`,
+ `/api/v1/search`, and `/api/v1/graph` to inspect the destination;
+- default to dry-run, printing planned page writes without mutating ai-memory.
+
+Write:
+
+- write imported or normalized pages through `/admin/write-page` or MCP
+ `memory_write_page`;
+- do not delete in v1;
+- use `memory_query` / `memory_read_page` or `/api/v1/search` / page reads for
+ duplicate detection and context checks;
+- optionally call `memory_consolidate` or `memory_auto_improve` after import for
+ post-import refinement, rather than building that refinement into core;
+- for bulk operations, loop over the public single-page operation unless ai-memory
+ later adds a generic bulk-mutation seam for its own reasons.
+
+Re-home by kind:
+
+- compute the move/link-rewrite plan in the companion;
+- apply moves as normal writes to the new path plus deletes of the old path;
+- preserve frontmatter that ai-memory returns through page reads;
+- fail closed on collisions, missing pages, or changed source hashes.
+
+### Safety requirements
+
+- Never open ai-memory's SQLite database or wiki directory directly.
+- Require an explicit destination workspace/project.
+- Preserve only metadata supported by the public write surface (`title`, `kind`,
+ `tier`, `tags`, `pinned`, and body) unless a future generic core seam adds
+ broader frontmatter support. Do not claim arbitrary frontmatter or author
+ preservation in companion imports.
+- Carry idempotency keys or source fingerprints in companion-side state so failed
+ imports can be resumed safely.
+- Surface all destructive actions in dry-run output before live mode.
+- Treat non-overwrite checks as best-effort unless/until core exposes a generic
+ compare-and-write seam; companion v1 re-checks before each write but cannot make
+ `/admin/write-page` atomic with that read.
+- Keep LLM normalization optional; deterministic import should work with no LLM.
+- Keep provider-specific performance tweaks, such as model parameter changes, out
+ of importer PRs. If ai-memory core needs a provider bugfix or optimization,
+ land it as a small standalone core change.
+
+### Implementation plan
+
+1. Build a read-only planner for one source format and snapshot fixtures.
+2. Add dry-run output and collision detection.
+3. Add live writes through existing ai-memory public write/delete surfaces.
+4. Add optional LLM normalization as a companion-side pass.
+5. Add re-home/link-rewrite as a separate subcommand after import is stable.
+6. Only after repeated usage, consider whether ai-memory core lacks a small,
+ generic API seam; do not start by patching core endpoints.
+
+## `ai-memory-web-editor`: browser chat/editor companion
+
+This is the companion shape for PR #123.
+
+### Goal
+
+Offer a richer browser product for chat, editing, and curation without turning
+the built-in `/web` browser into a write-capable application.
+
+The core built-in browser remains intentionally small: project list, tree view,
+markdown rendering, search, and other read-oriented inspection. A separate web
+editor can move faster and make stronger product decisions.
+
+### Product shape
+
+Prefer a separate repository with a backend plus frontend, for example:
+
+```text
+ai-memory-web-editor/
+├── crates/server/ # auth, CSRF, mutation broker, LLM orchestration
+├── crates/client/ # UI or generated assets
+├── src/ # if kept as a single binary crate initially
+└── tests/e2e/
+```
+
+The companion can be deployed next to ai-memory and reverse-proxied under a
+separate path or host, for example `https://memory.example.com/editor`, while
+ai-memory remains at `/api/v1`, `/mcp`, `/admin`, `/hook`, and `/web`.
+
+### How it talks to ai-memory
+
+Read:
+
+- use `/api/v1` for project lists, pages, recent pages, search, graph, briefing,
+ and overview data;
+- use the companion's own LLM provider for chat orchestration if it needs more
+ than raw page/search context.
+
+Write:
+
+- browser requests go to the companion backend, not directly to ai-memory admin
+ routes;
+- the companion backend performs CSRF checks, user/session policy, rate limiting,
+ and confirmation state;
+- after approval, it calls ai-memory's existing write/delete surfaces with a
+ server-side token.
+
+Mutation flow:
+
+1. The LLM proposes a patch, create, or delete as a pending action.
+2. The UI shows an explicit diff and the target workspace/project/path.
+3. The user confirms or rejects the pending action.
+4. The companion re-reads the current page and verifies the expected base hash.
+5. The companion applies the write/delete through ai-memory's public mutation
+ path and records its own audit trail.
+
+### Safety requirements
+
+- No auto-applied browser writes from an LLM response.
+- Deletes always require explicit confirmation.
+- Edits preserve existing metadata unless the user deliberately changes it.
+- Folder or search scope is a context limit, not a mutation boundary; the backend
+ must independently authorize the target page before applying a change.
+- If the UI advertises folder-scoped editing, the companion must enforce that
+ target paths stay inside the allowed folder or project on the server side.
+- The companion must not rely on cookie/basic auth to perform non-GET ai-memory
+ mutations from the browser. Use a server-side token and companion CSRF/session
+ protection.
+- In multi-user mode, `/admin/*` is root-only. A companion must either run with an
+ operator token or use MCP/tooling flows appropriate to the actor; it must not
+ assume normal user tokens can admin-write.
+- Propagate actor/author context where the public write surface supports it so
+ admission webhooks and audit stay meaningful.
+- Keep `/api/v1` read-only; do not ask core ai-memory to expose writable CORS
+ browser endpoints for this product.
+
+### Implementation plan
+
+1. Build a read-only editor shell against `/api/v1` first.
+2. Add chat over selected page/search context, still read-only.
+3. Add pending edit proposals with diff preview, but no apply button.
+4. Add confirmed writes through the companion backend and ai-memory public write
+ endpoints.
+5. Add confirmed deletes last.
+6. Keep the built-in `/web` UI unchanged unless core ai-memory independently
+ needs a small read-only API enhancement.
+
+## When to move a seam into core
+
+A companion may reveal a missing primitive that belongs in ai-memory. Move only
+small, generic seams into core, and only after the companion proves the need.
+
+Good core candidates:
+
+- a read-only API field needed by several clients;
+- a narrowly-scoped mutation endpoint that is equivalent to an existing MCP tool;
+- a capability check or scope-resolution helper that prevents duplicated security
+ logic.
+
+Poor core candidates:
+
+- source-specific import parsers;
+- UI workflows;
+- LLM chat prompts for editing;
+- project-specific scoring, pruning, or normalization policies;
+- companion-only admin commands.
+
+This keeps ai-memory stable while still allowing richer tools to grow around it.