Simplify TinyMemory into api, tools and integrations crates

.github/workflows/ci.yml

@@ -49,9 +49,9 @@ jobs:
         run: cargo test
 
       # `cargo build --all-targets` only compiles an example; AGENTS.md
-      # promises `cargo run -p tinymemory --example basic` works.
+      # promises `cargo run -p tinymemory-integrations --example basic` works.
       - name: Run the bundled example
-        run: cargo run -p tinymemory --example basic
+        run: cargo run -p tinymemory-integrations --example basic
 
       # The contract is what engines and hosts compile against. It must stay
       # free of storage engines, native libraries, HTTP clients and async
@@ -129,24 +129,39 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - name: no default features
+          - name: integrations, no default features
+            package: tinymemory-integrations
             features: --no-default-features
+          - name: cortex
+            package: tinymemory-integrations
+            features: --no-default-features --features cortex
           - name: documents
+            package: tinymemory-integrations
             features: --no-default-features --features documents
           - name: documents-office
+            package: tinymemory-integrations
             features: --no-default-features --features documents-office
           - name: sources network implication
+            package: tinymemory-integrations
             features: --no-default-features --features sources-network
           - name: safety
+            package: tinymemory-integrations
             features: --no-default-features --features safety
-          - name: context
-            features: --no-default-features --features context
           - name: legacy import
+            package: tinymemory-integrations
             features: --no-default-features --features legacy-import
-          - name: conformance
-            features: --no-default-features --features conformance
           - name: full aggregate
+            package: tinymemory-integrations
             features: --no-default-features --features full
+          - name: api, no features
+            package: tinymemory-api
+            features: --no-default-features
+          - name: api conformance
+            package: tinymemory-api
+            features: --features conformance
+          - name: tools
+            package: tinymemory-tools
+            features: ""
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
@@ -157,7 +172,7 @@ jobs:
       - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2
 
       - name: Test
-        run: cargo test -p tinymemory ${{ matrix.features }}
+        run: cargo test -p ${{ matrix.package }} ${{ matrix.features }}
 
   docs:
     name: Docs
@@ -189,7 +204,7 @@ jobs:
         run: |
           set -euo pipefail
           msrv="$(cargo metadata --format-version 1 --no-deps \
-            | jq -r '.packages[] | select(.name == "tinymemory") | .rust_version')"
+            | jq -r '.packages[] | select(.name == "tinymemory-api") | .rust_version')"
           if [[ -z "$msrv" || "$msrv" == "null" ]]; then
             echo "package.rust-version is not set in Cargo.toml" >&2
             exit 1

.github/workflows/release.yml

@@ -60,10 +60,10 @@ jobs:
         run: |
           set -euo pipefail
 
-          # The root manifest is a virtual workspace, so name the facade
-          # rather than taking whichever package cargo lists first.
+          # Every crate inherits `version` from `[workspace.package]`, so any
+          # one of them names the current version; read the contract crate's.
           metadata="$(cargo metadata --format-version 1 --no-deps)"
-          crate_name="tinymemory"
+          crate_name="tinymemory-api"
           current_version="$(
             jq -r --arg name "$crate_name" \
               '.packages[] | select(.name == $name) | .version' <<< "$metadata"
@@ -96,9 +96,10 @@ jobs:
             echo "tag=${tag}"
           } >> "$GITHUB_OUTPUT"
 
-      # Bumps the facade's `[package]` version only. That is sufficient because
-      # no intra-workspace path dependency carries a `version = "…"`
-      # requirement; the guard below keeps it that way.
+      # Bumps `[workspace.package] version` in the root manifest, which every
+      # crate inherits. That is sufficient because no intra-workspace path
+      # dependency carries a `version = "…"` requirement; the guard below
+      # keeps it that way.
       - name: Update crate version
         env:
           CRATE_NAME: ${{ steps.version.outputs.crate_name }}
@@ -117,9 +118,15 @@ jobs:
             exit 1
           fi
 
-          perl -0pi -e 's/(\[package\][\s\S]*?\nversion = ")[^"]+(")/$1$ENV{NEXT_VERSION}$2/' \
-            crates/tinymemory/Cargo.toml
-          cargo update -p "$CRATE_NAME" --precise "$NEXT_VERSION"
+          perl -0pi -e 's/(\[workspace\.package\][\s\S]*?\nversion = ")[^"]+(")/$1$ENV{NEXT_VERSION}$2/' \
+            Cargo.toml
+          cargo update --workspace
+          current="$(cargo metadata --format-version 1 --no-deps \
+            | jq -r --arg name "$CRATE_NAME" '.packages[] | select(.name == $name) | .version')"
+          if [[ "$current" != "$NEXT_VERSION" ]]; then
+            echo "Version bump did not take: $CRATE_NAME is $current, expected $NEXT_VERSION" >&2
+            exit 1
+          fi
 
       - name: Commit version bump and tag
         env:
@@ -128,7 +135,7 @@ jobs:
           set -euo pipefail
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git add crates/tinymemory/Cargo.toml Cargo.lock
+          git add Cargo.toml Cargo.lock
           git commit -m "Release ${RELEASE_TAG}"
           git tag -a "${RELEASE_TAG}" -m "Release ${RELEASE_TAG}"
 

AGENTS.md

@@ -11,18 +11,27 @@ no longer applies rather than leaving it to rot.
 
 This is a Cargo **workspace** with a virtual root: there is no root package,
 and every crate lives in its own directory under `crates/`, named for the
-package it holds. `members` is the glob `crates/*`, so a new crate joins the
-workspace by existing. `crates/tinymemory` is the facade a host depends on;
-`crates/tinymemory-api` is the contract; `crates/tinymemory-cortex` is the
-CortexDB engine; the rest are subsystems, each reachable from the facade by a
-feature named after it. The accepted behaviour is
-[`docs/specs/memory-v2.md`](docs/specs/memory-v2.md).
+package it holds. There are exactly three, one per part of the memory layer:
+
+- `crates/tinymemory-api` — the **core contract**: `MemoryEngine`, items,
+  metadata, namespaces, errors, and (feature `conformance`) the suite every
+  engine must pass. No I/O.
+- `crates/tinymemory-tools` — the **agent tool spec**: `MemoryTools` over any
+  engine, and the `context.md` compiler.
+- `crates/tinymemory-integrations` — the **integrations**: the CortexDB engine
+  and its registry, documents, sources, safety and the legacy v1 import, each
+  a module behind a feature.
+
+Shared package metadata, the version and the lint table live in the root
+`Cargo.toml` (`[workspace.package]`, `[workspace.lints]`). The accepted
+behaviour is [`docs/specs/memory-v2.md`](docs/specs/memory-v2.md); how it is
+built is in [`docs/architecture/`](docs/architecture/README.md).
 
 See [`README.md`](README.md) for the full layout and the feature table.
 
 ```text
 crates/<package>/
-├── Cargo.toml          # one package; `[lints]` opted into per crate
+├── Cargo.toml          # one package; `[lints] workspace = true`
 ├── README.md           # required of complex crates: design, surface, caveats
 └── src/
     ├── lib.rs          # crate docs + the entire public re-export surface
@@ -39,10 +48,11 @@ docs/
 └── adr/                # immutable architecture decision records
 ```
 
-A new crate goes in `crates/<package>/`, and a package that is not an engine
-or a subsystem of the memory layer probably does not belong here at all. Reach
-it from the facade by adding an optional dependency and a feature of the same
-name, so a host keeps taking one dependency and stating what it wants.
+Do not add a fourth crate. New contract surface goes in `tinymemory-api`, a new
+agent-facing tool in `tinymemory-tools`, and anything that talks to the outside
+world (a new engine, reader or converter) becomes a module of
+`tinymemory-integrations` behind a feature named after it, with its
+dependencies optional and enabled only by that feature.
 
 Each feature area belongs in a focused module directory under the crate's
 `src/`. A module root explains the module, wires its pieces together, and
@@ -83,7 +93,7 @@ Supporting commands:
 
 - `cargo fmt --all` — format before committing.
 - `cargo test <filter>` — run a focused subset while iterating.
-- `cargo run -p tinymemory --example basic` — run the bundled example. The
+- `cargo run -p tinymemory-integrations --example basic` — run the bundled example. The
   `-p` is required: the workspace root is virtual, so cargo cannot infer which
   package an example belongs to.
 - `cargo doc --no-deps --all-features` — build the rustdoc CI also builds with
@@ -107,8 +117,8 @@ Use standard `rustfmt` output and Rust 2024 idioms. Do not hand-format around
   `impl Into<String>` at boundaries; return owned, concrete types.
 - Keep the public surface minimal: default to private, and export deliberately
   from the crate's `src/lib.rs`.
-- `unsafe` is forbidden crate-wide by the `[lints]` table in each crate's own
-  `Cargo.toml` — the root is virtual and carries no lint configuration. If a
+- `unsafe` is forbidden in every crate by `[workspace.lints]` in the root
+  `Cargo.toml`, which each crate inherits with `[lints] workspace = true`. If a
   crate genuinely needs it, relax the lint in its own commit and document every
   invariant with a `// SAFETY:` comment.
 
@@ -222,7 +232,8 @@ explicitly declined with a reason.
 Releases run from `.github/workflows/release.yml` via a manual
 `workflow_dispatch` with a `patch` / `minor` / `major` bump. The workflow
 re-runs formatting, clippy, tests, and rustdoc, computes the next version,
-updates `crates/tinymemory/Cargo.toml` and `Cargo.lock`, commits and tags
+updates `[workspace.package] version` in the root `Cargo.toml` and
+`Cargo.lock`, commits and tags
 `vX.Y.Z`, pushes both, and creates a GitHub release for the tag. There are no
 binary artifacts.
 
@@ -231,7 +242,7 @@ take this repository by git or path, pinned to a tag.
 
 Consequently:
 
-- Do not hand-edit the `version` field in `crates/tinymemory/Cargo.toml`; the
+- Do not hand-edit `[workspace.package] version` in the root `Cargo.toml`; the
   release workflow owns it.
 - Follow semantic versioning. Any change to the public surface that is not
   purely additive is a breaking change and needs a major bump.