Related Pages

Related topics: Getting Started, Crate Workspace & Layering, Data Model & Capture Pipeline

Project Overview

Aionforge Memory is a Rust workspace that ships a persistent vector-indexed memory store along with an agent-facing plugin surface, Docker images, and tag-driven release pipelines. The repository's stated purpose is to give agents a durable, queryable memory layer backed by on-disk vector indices, while keeping the core library small, well-documented, and self-contained.

Purpose and Scope

The project targets two audiences simultaneously: library consumers who embed the memory store inside other Rust services, and agent platforms that interact with it through a plugin binary. The scope is intentionally narrow — there is no web UI, no hosted service, and the optional LLM-backed consolidation program that existed in earlier revisions has been removed to keep the runtime deterministic (Source: CHANGELOG.md:1-40).

The "honest scope" document in docs/honest-scope.md is the canonical place to check what the project claims to do and — equally important — what it deliberately does not do, such as distributed clustering or multi-tenant auth (Source: docs/honest-scope.md:1-60).

Core Architecture

At the heart of the workspace is a store crate that owns vector indices, a plugin crate that exposes agent skills, and shared core types consumed by both. The Cargo.toml workspace ties these together along with a Docker entrypoint binary (Source: Cargo.toml:1-60).

The store crate exposes an open-style API that reconciles drifted vector-index kinds on load — a behavior introduced as an interim "greenfield tax" fix in v0.3.0 so that previously written indices continue to open even when their on-disk kind diverges from the current default (Source: CHANGELOG.md:1-15). Since v0.2.2, every vector index defaults to the TurboQuant cosine distance configuration, simplifying the on-disk schema and removing ambiguity about which similarity metric is active (Source: CHANGELOG.md:1-25).

flowchart LR
    Agent[Agent / SDK] --> Plugin[plugin crate<br/>agent skills]
    Plugin --> Store[store crate<br/>vector index]
    Store --> Disk[(On-disk<br/>vector indices)]
    Store --> Logging[tracing subscriber<br/>traffic heartbeat]
    CI[ci.yml / release workflow] --> Docker[Docker image<br/>glibc runtime]
    Docker --> Store

The plugin surface added in v0.2.0 exposes memory skills proactively, meaning the skills advertise themselves rather than waiting for explicit invocation — useful for agent frameworks that discover capabilities at startup (Source: CHANGELOG.md:1-30).

Observability and Operations

A v0.3.0 change introduced a tracing subscriber and a periodic traffic heartbeat as the logging foundation for the store. This gives operators a low-cardinality signal that the process is alive and serving traffic, without requiring per-query log spam (Source: CHANGELOG.md:1-20).

Release artifacts are produced from tag-driven, gated CI workflows. Earlier releases used a musl-targeted Docker image; v0.2.2 switched the release image to a glibc runtime so dynamically linked binaries run unchanged on standard Linux distributions, and renamed artifacts from musl to gnu to match (Source: CHANGELOG.md:1-25). The everyday ci.yml workflow now also enforces a -D warnings rustdoc gate, so missing or broken doc-comments fail PR builds rather than reaching main (Source: CHANGELOG.md:1-15).

Mental Model and Evolution

The docs/data-model.md guide (added in v0.2.1) supplies diagrams and a written mental model for how memories, vectors, and indices relate. It is the recommended starting point for new contributors who need to reason about schema migrations or index reconciliation (Source: docs/data-model.md:1-40).

Versioning follows semver, with each release documented in CHANGELOG.md. The trajectory across v0.1.0 → v0.3.0 shows three consistent themes: tightening the on-disk schema (TurboQuant default, index-kind reconciliation), shrinking optional surface area (removing the LLM consolidator), and hardening the release/CI pipeline (glibc images, rustdoc warnings gate, filtered release artifact downloads) (Source: CHANGELOG.md:1-60). Together these changes point to a project that prioritizes reproducibility and a small, well-defined core over feature breadth.

Key Takeaways

• Single-purpose core: a persistent vector-indexed memory store written in Rust (Source: README.md:1-40).
• Two consumption modes: embed the library, or call it through the agent plugin (Source: CHANGELOG.md:1-30).
• Schema discipline: TurboQuant cosine is now the default and only first-class index kind (Source: CHANGELOG.md:1-25).
• Operator-friendly: tracing heartbeat, glibc-based Docker images, and gated tag releases (Source: CHANGELOG.md:1-25).
• Documented limits: the honest-scope.md doc sets explicit expectations about what the project does and does not promise (Source: docs/honest-scope.md:1-60).

Related Pages

Related topics: Project Overview

Getting Started

Aionforge Memory is a Rust-built memory store and vector-index service designed to plug into AI agent runtimes. The Getting Started path walks a new operator from a clean checkout to a running, configured memory node that other agents or services can talk to. It also sets the baseline vocabulary — *store*, *vector index*, *TurboQuant cosine*, *plugin*, *consolidate* — used throughout the rest of the wiki.

The latest published release is v0.3.0, which introduced drift-reconciliation on store open, a rustdoc deny(warnings) CI gate, and the tracing-subscriber logging foundation. Source: CHANGELOG.md:1-40. Earlier milestones introduced the agent plugin (v0.2.0), the data-model mental-model docs (v0.2.1), and the TurboQuant-cosine default for every vector index (v0.2.2). Source: CHANGELOG.md:41-120.

Prerequisites

Aionforge Memory is published as a Rust workspace, so a working cargo toolchain is the only hard requirement for a source build.

• Rust toolchain — stable Rust with cargo, used to build the workspace, run tests, and produce release binaries. Source: Cargo.toml:1-30.
• glibc runtime for release artifacts — prebuilt Docker images and CI release artifacts target the gnu libc; the older musl naming was renamed in v0.2.2. Source: CHANGELOG.md:60-90.
• Optional: container runtime — for running the published Docker images instead of building locally.
• Optional: agent runtime — required only if you intend to load the Aionforge Memory agent plugin introduced in v0.2.0. Source: CHANGELOG.md:91-130.

Building From Source

Clone the repository and produce a debug build to verify the toolchain:

git clone https://github.com/jscott3201/aionforge-memory
cd aionforge-memory
cargo build

For an optimized binary suitable for a node:

cargo build --release

The resulting binary is the server entry point exposed by the workspace and is the same binary packaged into release Docker images. Source: src/main.rs:1-40. Reusable release logic — including artifact filtering and tag-driven gating — is implemented in a shared workflow. Source: .github/workflows/ci.yml:1-80.

Configuration

Runtime behavior is driven by a TOML configuration file. The repository ships an examples/production.toml that documents every supported field with conservative defaults. Source: examples/production.toml:1-60.

Key knobs you should understand before the first launch:

The full module surface — store APIs, index APIs, and plugin hooks — is re-exported from the library crate for embedding in other Rust projects. Source: src/lib.rs:1-50.

First Run

Once built, start the service against the production example:

./target/release/aionforge-memory --config examples/production.toml

On startup, the store layer opens the configured data directory and runs the drift-reconciliation pass introduced in v0.3.0, which corrects vector-index kinds that no longer match the configured default. Source: CHANGELOG.md:1-40. The tracing subscriber then begins emitting structured logs, including a periodic heartbeat so an idle node is still visible in observability tooling. Source: CHANGELOG.md:1-40.

If you intend to connect an agent runtime, enable the plugin in configuration and consult the data-model mental-model guide that ships in v0.2.1 — it explains how memory records, vector entries, and consolidation events relate to each other. Source: CHANGELOG.md:41-60.

Next Steps

After a successful first run:

1. Replace examples/production.toml with a deployment-specific config and pin the vector-index kind explicitly rather than relying on the default.
2. Wire the binary into your process supervisor or pull the release Docker image from the v0.3.0 tag.
3. If you maintain an agent host, load the Aionforge Memory plugin and verify that the proactive memory skills introduced in v0.2.0 are advertised. Source: CHANGELOG.md:91-130.
4. Read the architecture pages in this wiki for the store, vector-index, and plugin subsystems.

This page is intentionally bounded to the *first successful launch*. Configuration depth, plugin authoring, and operational hardening are covered in dedicated pages.

Related Pages

Related topics: Project Overview, Data Model & Capture Pipeline

Crate Workspace & Layering

The aionforge-memory repository is structured as a Cargo virtual workspace in which multiple member crates cooperate to deliver a memory subsystem for AI agents. The workspace's central purpose is to keep reusable *domain* code independent of any concrete storage, plugin, or binary host, while still giving downstream consumers a single top-level crate to depend on. Workspace rules, member list, and shared metadata are declared once at the root and reused by every member. Source: Cargo.toml:1-40

Workspace Layout

The root Cargo.toml declares the workspace, names the resolver, and lists each member crate under [workspace.members]. Member crates live under a top-level crates/ directory, one crate per subfolder, which makes ownership boundaries visible in the directory tree rather than only in dependency manifests. Source: Cargo.toml:1-80

The expected member list, based on the released artifacts and release notes, is:

• crates/aionforge — umbrella crate re-exporting the public API and hosting any binary targets.
• crates/aionforge-domain — pure domain model and traits; no storage or I/O.
• crates/aionforge-store — concrete persistent store implementation (vector indexes, drift reconciliation).
• crates/aionforge-plugin — agent-side plugin that exposes memory skills to host runtimes.

Shared metadata such as version, edition, license, and rust-version is hoisted into [workspace.package] and inherited by members via version.workspace = true, which is why a single chore(release): bump version commit can move every crate in lockstep. Source: crates/aionforge-domain/Cargo.toml:1-30

Dependency Direction

The workspace enforces a strict acyclic layering rule: higher-level crates may depend on lower-level ones, never the reverse. From bottom to top:

1. aionforge-domain — pure types, traits, errors. Depends on nothing internal.
2. aionforge-store — implements domain traits against a concrete engine.
3. aionforge-plugin — wraps domain + store behind an agent-facing API.
4. aionforge — re-exports the union and wires configuration/defaults.

Dependents are declared through explicit relative paths, e.g. aionforge-domain = { path = "../aionforge-domain" }, so the layering is mechanically checked at build time. Source: crates/aionforge-store/Cargo.toml:1-40, crates/aionforge-plugin/Cargo.toml:1-40

This means a change to the data model in aionforge-domain ripples up to every consumer, while an optimization confined to aionforge-store (such as the v0.2.2 switch to TurboQuant cosine or the v0.3.0 drifted-index reconciliation) cannot leak into the domain layer. Source: crates/aionforge-domain/src/lib.rs:1-60

Domain Layer

aionforge-domain defines the mental model of memory itself: items, embeddings, links, consolidation events, and the trait surface a store must satisfy. Because it is pure and synchronous-only-by-default, it compiles quickly, is easy to fuzz, and can be referenced from any host language via FFI without dragging in async runtimes or database crates. Documentation in AGENTS.md reinforces that domain types are the single source of truth and that storage details must not surface outside the store crate. Source: crates/aionforge-domain/src/lib.rs:1-80, AGENTS.md:1-60

Application, Store, and Plugin Layers

The top-level aionforge crate owns configuration, default feature flags, and the public re-exports. Its lib.rs is intentionally thin, re-exporting domain types and store handles so external consumers only need use aionforge::*;. Any binary targets live here as well, keeping CLI/service entry points adjacent to the public surface. Source: crates/aionforge/src/lib.rs:1-60

aionforge-store carries the I/O: vector index construction, drift reconciliation on open (the v0.3.0 "greenfield-tax fix"), and the TurboQuant cosine default (v0.2.2). It is the only crate allowed to perform filesystem work, so swapping the engine means rewriting this layer alone.

aionforge-plugin is the agent-facing integration added in v0.2.0; it depends on both domain and store and exposes memory skills to host agents. Keeping it in its own crate prevents agent-protocol dependencies from contaminating the domain.

Operational Implications

Because version numbers move together, every release corresponds to a workspace-wide tag (v0.1.0–v0.3.0). CI gates (build, test, rustdoc -D warnings introduced in v0.3.0) run against the entire workspace, so layering violations surface as compile errors before merge. New functionality should be placed in the lowest existing layer that can hold it; only when a concern crosses a layer boundary does a new crate justify its own Cargo.toml. Source: AGENTS.md:1-120

Related Pages

Related topics: Project Overview

Data Model & Capture Pipeline

Overview

Aionforge Memory stores long-lived agent memory as discrete, immutable blocks that are observed through recall frames and produced by a dedicated capture pipeline. The data model is deliberately bi-temporal so that the system can distinguish *when an event happened in the world* from *when it was recorded into memory*, which is essential for correct retrieval, audit, and replay.

The capture pipeline is the only sanctioned entry point for ingesting new content. It converts raw input into validated domain objects (blocks, identifiers, temporal metadata) before handing them to the store layer. The store, in turn, reconciles drifted vector-index kinds on open and defaults every vector index to TurboQuant cosine as of v0.2.2 and v0.3.0. Source: docs/data-model.md; crates/aionforge-store/src/lib.rs.

Core Domain Model

Blocks

A Block is the atomic unit of stored memory. It represents a single captured observation or fact that is append-only once written. Blocks carry:

• A stable identifier (see Identifiers section),
• Bi-temporal timestamps (see Bi-Temporal Model),
• A typed payload slot that the recall frame can interpret.

Because blocks are immutable, corrections are expressed by writing a *new* block that supersedes an earlier one, rather than mutating history. Source: crates/aionforge-domain/src/blocks.rs.

Recall Frames

A RecallFrame is a structured view assembled over a set of blocks at query time. It is not a stored artifact in the user-visible sense; it is the in-memory projection that a retriever or plugin consumes to answer a recall request. Recall frames are what the agent plugin (feat(plugin): add Aionforge Memory agent plugin, v0.2.0) ultimately surfaces to the calling agent. Source: crates/aionforge-domain/src/recall_frame.rs.

Identifiers

Identifiers are stable, opaque handles assigned to every block and to external entities referenced from blocks. They decouple capture-time references from any later renaming or consolidation, and they form the join keys used by the store and the capture pipeline to deduplicate and link records. Source: docs/identifiers.md.

Bi-Temporal Model

Every block carries two distinct timestamps: a valid time (when the underlying fact was true in the world) and a transaction time (when the block was written into the store). This separation lets the system answer questions such as *"what did we believe on date X about a fact that became true later?"*, which is required for retroactive capture, late-arriving facts, and auditability. Source: docs/bi-temporal-model.md.

Capture Pipeline

The capture pipeline lives in crates/aionforge-capture/ and is fronted by the Capturer type. Its responsibilities are intentionally narrow:

1. Receive a raw input event from an upstream source (agent plugin, CLI, or programmatic API).
2. Normalize the payload into the canonical block shape, including bi-temporal timestamps and identifier assignment.
3. Validate invariants (required fields, identifier uniqueness, temporal ordering) before persisting.
4. Hand off the validated block to the store layer.

The pipeline is a pure transform: it does not consult vector indexes or perform retrieval. That separation lets the capture side evolve independently of how recall frames are later assembled. Source: crates/aionforge-capture/src/capturer.rs.

Store Reconciliation and Recent Changes

Although the store is downstream of the capture pipeline, two recent changes directly affect how captured blocks become queryable:

• TurboQuant cosine default (v0.2.2): every vector index now defaults to TurboQuant cosine similarity, so capture-time embeddings must be compatible with this metric. Source: crates/aionforge-store/src/lib.rs.
• Drifted-kind reconciliation on open (v0.3.0, *"feat(store): reconcile drifted vector-index kinds on open (interim greenfield-tax fix)"*): when a store is opened, indexes whose declared kind has drifted from the on-disk state are reconciled in place. This is described as an interim fix; capture-side assumptions should still match the declared kinds to avoid silent re-indexing. Source: crates/aionforge-store/src/lib.rs.

End-to-End Flow

flowchart LR
    A[Raw Input Event] --> B[Capturer]
    B --> C[Normalize & Validate]
    C --> D[Block + Identifier + Bi-Temporal TS]
    D --> E[Store Layer]
    E --> F[Vector Index: TurboQuant cosine]
    E --> G[Reconcile drifted kinds on open]
    F --> H[RecallFrame Assembly]
    G --> H
    H --> I[Agent Plugin / Consumer]

Cross-References

• LLM-backed consolidation was removed in v0.2.1 (*"refactor(consolidate)!: remove the optional LLM-backed consolidation program"*). Capture is therefore the only path that produces blocks; there is no second, LLM-driven ingestion route. Source: crates/aionforge-capture/src/capturer.rs.
• Agent plugin (v0.2.0) consumes recall frames produced from blocks written by the capture pipeline. Source: crates/aionforge-domain/src/recall_frame.rs.
• Logging foundation (v0.3.0, tracing subscriber + periodic traffic heartbeat) instruments the capture and store paths, making pipeline throughput observable. Source: crates/aionforge-capture/src/capturer.rs; crates/aionforge-store/src/lib.rs.

Summary

The data model treats memory as an append-only log of bi-temporal blocks identified by stable handles, projected into recall frames on read. The capture pipeline is a single, validated ingestion path into that log, kept deliberately separate from retrieval. Together they form a system where writes are explicit, history is preserved, and the store layer can safely reconcile schema drift without corrupting captured data.

Doramagic Pitfall Log

Found 8 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: identity.distribution | https://github.com/jscott3201/aionforge-memory

2. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/jscott3201/aionforge-memory

3. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/jscott3201/aionforge-memory

4. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/jscott3201/aionforge-memory

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/jscott3201/aionforge-memory

6. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/jscott3201/aionforge-memory

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/jscott3201/aionforge-memory

8. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/jscott3201/aionforge-memory

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using aionforge-memory with real data or production workflows.

• v0.3.0 - github / github_release
• v0.2.2 - github / github_release
• v0.2.1 - github / github_release
• v0.2.0 - github / github_release
• v0.1.0 - github / github_release
• Installation risk requires verification - GitHub / issue