cortext 1.3.1

Rust bindings for the Cortext multimodal memory engine
Documentation
# cortext.rs

Rust bindings for [Cortext](https://github.com/augmem/cortext) — no C compiler
required at build time. The crate loads the `cortext.cpp` shared library at
runtime via [`libloading`](https://docs.rs/libloading).

Natives and AIST model shards are **not** in this crate. On first use the
package downloads the matching [augmem/cortext.cpp](https://github.com/augmem/cortext.cpp/releases)
release asset, verifies its SHA-256, and unpacks it:

```text
cortext-assets-<version>.tar.gz
cortext-assets-<version>.tar.gz.sha256
```

Default assets version: **1.3.0** (`ASSETS_VERSION`).

## Install

```toml
[dependencies]
cortext = "1.3.1"
```

```bash
cargo add cortext@1.3.1
```

## Use

```rust,no_run
fn main() -> Result<(), cortext::Error> {
    let memory = cortext::Cortext::new(":memory:", None)?;
    let ctx = memory.process_text("Bailey likes tennis balls.", "chat/main")?;
    println!("{:?}", ctx.get("should_interrupt"));

    let with_media = memory.process_text_with_media(
        "Bailey sent a voice note.",
        "chat/main",
        Some(&cortext::Media {
            data: vec![0x00, 0xff, 0x01],
            mime_type: "audio/ogg".into(),
        }),
    )?;
    println!("{:?}", with_media.get("should_interrupt"));

    let embedding = memory.embed_text("embed without storing")?;
    println!("{}", embedding.len());
    Ok(())
}
```

`process_text` remains available for text-only input. To retain source media
alongside text, use `process_text_with_media`. `Media.data` is passed as
arbitrary binary and `Media.mime_type` / [`Media::mimetype`] is preserved as
supplied. `ProcessOptions.include_embedding` matches Python
(`true` by default); `omit_embedding` wins if both are set.

Custom stores match Python `DBProvider` / `ObjectStoreProvider`:

```rust,ignore
let memory = cortext::Cortext::with_store(None, MyDb)?;
let memory = cortext::Cortext::with_object_store(":memory:", None, MyObjects)?;
let memory = cortext::Cortext::with_store_and_object(None, MyDb, MyObjects)?;
```

## Assets

| Env | Purpose |
| --- | --- |
| `CORTEXT_ASSETS_VERSION` | Release version to fetch (default `1.3.0`) |
| `CORTEXT_ASSETS_DIR` | Pre-unpacked release tree (`native/` + `models/`) — skips download |
| `CORTEXT_ASSETS_URL` | Override archive URL |
| `CORTEXT_ASSETS_SHA256` | Override expected archive checksum |
| `CORTEXT_ASSET_CACHE_DIR` | Parent cache dir for downloaded versions |
| `CORTEXT_LIBRARY_PATH` | Explicit shared library path (skips asset native selection) |
| `CORTEXT_AIST_MODEL_PATH` | Explicit full `.gguf` only when you need one on disk |

Load order:

1. `CORTEXT_LIBRARY_PATH` if set
2. Otherwise `ensure_assets()` → `native/<platform-tag>/…` from the release tarball

Release natives embed AIST and assemble it on first create. `materialize_model`
is optional and always reads chunks from the same release asset tree.

## Develop

```bash
cargo test -p cortext
CORTEXT_ASSETS_DIR=/path/to/unpacked/assets cargo test -p cortext
```

## License

Apache-2.0. Native engine binaries come from `augmem/cortext.cpp` releases.