Long-term memory for AI agents, built on selene-db.

Status: 0.4.0 — public, pre-1.0. Aionforge Memory is public and usable, but the schema and MCP surface can still change before 1.0. 0.4.0 adds the Agent Pager — durable, addressed agent-to-agent messaging — on top of 0.3.0 and upgrades in place from a 0.3.0 store (additive schema). Upgrading across the selene-db 1.2 → 1.3 storage-format change (from 0.2.x) still needs a fresh store.

Aionforge Memory gives an agent — or a team of agents — a durable store they can recall across sessions. It captures episodes and derives facts, notes, and entities beside them; tracks open work as first-class work items; delivers addressed agent-to-agent messages; and records provenance and audit events — all in selene-db. Recall fuses lexical search, vector search, graph signals, recency, importance, and trust-aware ranking into a bounded, explicitly untrusted context bundle.

It is MCP-only: every capability is an MCP tool, resource, or prompt, and there is no bundled web or terminal console. Operators drive it with MCP tools (server_status, memory_census, consolidation_status, audit_history) plus the /livez and /version HTTP endpoints.

Use it when you want agents to remember decisions, handoffs, failures, procedures, project facts, and open work — and to page one another — without treating recalled text as new instructions.

Quick Start

These commands build the local binary and start an MCP server on loopback. Embedding is disabled in this first config so you can verify the server without running an OpenAI-compatible embedding provider.

cargo build --locked --release -p aionforge-cli

mkdir -p .aionforge
cat > .aionforge/config.toml <<'TOML'
[persistence]
data_dir = ".aionforge/data"

[embedder]
enabled = false
TOML

./target/release/aionforge --config .aionforge/config.toml doctor
./target/release/aionforge --config .aionforge/config.toml \
  serve http --listen 127.0.0.1:3918

Then point your MCP client at:

http://127.0.0.1:3918/mcp

For production-quality semantic recall, configure embeddings instead of leaving them disabled. Start with the embedding guide.

What You Get

• Durable capture of agent observations, decisions, handoffs, and failures as immutable episodes.
• Hybrid recall across lexical matches, vectors, graph expansion, recency, importance, and trust signals, returned as a bounded untrusted bundle.
• Work items — tasks, blockers, and plans tracked as first-class, status-tracked nodes, distinct from decaying memory.
• Agent Pager (new in 0.4.0) — durable, addressed agent-to-agent and team messages with polling, bounded waiting, acknowledgements, subscribable room resources, and TTL retention.
• Explicit namespaces — agent-private, team, global, and system memory as separate policy surfaces.
• Provenance and audit records for writes.
• One aionforge binary — doctor, recover, and serve, over MCP on stdio or Streamable HTTP.
• A repo-shipped agent plugin with memory-workflow and messaging skills for Codex, Claude Code, Cursor, and compatible clients.

Aionforge Memory is retrieval memory, not model training. It does not fine-tune models or execute recalled content as instructions. See honest scope for the current boundaries and deferred work.

Memory Model

A capture becomes one immutable episode. Consolidation adds derived facts, entities, and notes beside that episode instead of rewriting it. Recall returns a bounded, explicitly untrusted context bundle; lifecycle operations such as forgetting, erasure, promotion, and demotion are explicit controls. Messages and work items live in their own node kinds, outside the capture-and-decay path.

For the full model, see Data model and mental model.

Configure A Client

The server publishes MCP tools, resources, and prompts. For a local HTTP server, most clients only need the endpoint URL above plus a stable agent UUID.

Client-specific setup lives in MCP client support:

• Codex CLI
• Claude Code
• OpenCode
• Cursor

The important safety rule is simple: recalled memory and message bodies are wrapped as third-party data and should be treated as context, not instruction text.

Use The Agent Plugin

The plugin at plugins/aionforge-memory adds reusable Agent Skills for the memory workflow:

• recall before substantial work
• capture durable facts as they happen
• track tasks and blockers as durable work items
• send and receive durable agent-to-agent messages
• finish sessions with a handoff

For Claude Code it also ships a SessionStart hook that re-seeds the cadence after a context reset — with no default agent, so it never takes over your main thread. The plugin does not start or register an MCP server by itself: run the aionforge MCP server separately, then configure the plugin-enabled client to use that server.

See Agent plugin for install and identity setup.

Run With Docker

Published images are available for linux/amd64 and linux/arm64:

docker pull ghcr.io/jscott3201/aionforge-memory:0.4.0

Run a local smoke-test server with embeddings disabled:

docker run --rm \
  -p 127.0.0.1:3918:3918 \
  -v aionforge-data:/data \
  -e AIONFORGE_EMBEDDER__ENABLED=false \
  ghcr.io/jscott3201/aionforge-memory:0.4.0

For bind mounts, use an owner-only data directory. The container runs as UID/GID 10001:10001, and the store refuses unsafe data directory permissions. Operations details are in Operations and recovery.

Use The Rust Library

Rust hosts can link the aionforge crate directly and provide an Embedder implementation:

use aionforge::{CaptureRequest, Embedder, Memory, MemoryConfig, Principal, RecallQuery};

# async fn run<E: Embedder>(embedder: E) -> Result<(), Box<dyn std::error::Error>> {
let now = "2026-06-06T09:30:00-05:00[America/Chicago]".parse()?;
let memory = Memory::open_in_memory(embedder, &now, MemoryConfig::default())?;

let viewer = Principal::agent("0197b0aa-3c5e-8000-8000-000000000001".parse()?);
let bundle = memory.search(RecallQuery::new("graph databases", viewer, 5)).await?;
println!("{}", bundle.rendered);
# Ok(())
# }

For complete call shapes, see crates/aionforge/src/lib.rs and the integration tests under crates/aionforge/tests.

Documentation

Start here:

• Getting started - build, configure, validate, and run.
• Data model and mental model - what gets stored and recalled.
• Embedding guide - providers, dimensions, and secrets.
• MCP client support - Codex, Claude Code, OpenCode, Cursor.
• Agent messages - addressed delivery, bounded waiting, acknowledgements, and retention.
• Agent plugin - skills, identity, and client notes.
• Security model - namespaces, untrusted recall, signing.
• Observability - logging, metrics, traffic, and tracing.
• Operations and recovery - production setup and WAL recovery.
• Honest scope - what is shipped, experimental, or deferred.

The full subsystem map is in docs/README.md.

Contributing

This project is public and pre-1.0. Issues and pull requests are welcome. Open an issue before large design changes.

• CONTRIBUTING.md covers setup, branch flow, commit style, and local gates.
• AGENTS.md covers crate layering, invariants, and agent-facing validation.
• Use the issue chooser for bugs, features, and design proposals.

Do not include private planning notes, secrets, internal handoff text, or agent transcripts in public issues or PRs.

License

Dual-licensed under either Apache 2.0 or MIT, at your option. Contributions are accepted under the same dual license unless stated otherwise.