convez.ai
MCP ServerAutomaçãoAvançado
jscott3201

aionforge-memory

jscott3201/aionforge-memory

Memória durável e recuperável para agentes IA com proveniência e grafo temporal

Ver no GitHub
BomPluginScore · de 0 a 100

A Rust-native agentic memory substrate built on the selene-db graph engine: a bi-temporal knowledge graph, hybrid retrieval, and an optional MCP server.

Instalação

$npx convez-ai jscott3201/aionforge-memory

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
12
Forks
1
Acompanhando
1
Saúde
85%
Último commit
há 4 meses
Versão
v0.4.0
Issues abertas
1
Contribuidores
1

Casos de uso

  • Persistência de contexto entre sessões de agentes
  • Rastreamento de decisões, procedimentos e falhas com auditoria
  • Recuperação inteligente de fatos e padrões sem contaminar instruções
  • Trabalho colaborativo entre múltiplos agentes com namespaces controlados

Veredito

MCP server robusto e bem arquitetado para memória de agentes, com abordagem rigorosa de proveniência e bi-temporalidade. Codebase maduro em Rust (v0.2.2), mas ainda em evolução pré-1.0 com APIs sujeitas a mudanças — recomendado para quem precisa de memória durável em sistemas de agentes críticos.

README

A tradução para o português deste README ainda está na fila.

Status: 0.2.2 public release. The Rust library, CLI, MCP server, read-only operator TUI, Docker image, and red-team gates are in place. A small sanitized retrieval regression corpus is in place; broader retrieval-quality benchmarks remain deferred. Expect schema and API changes before 1.0; the read-only TUI is slated to be replaced by an operator console in a later release.

Aionforge Memory is a Rust memory layer for agent systems. It stores episodes, facts, notes, skills, bad patterns, work items, core memory, and audit events in selene-db, then retrieves relevant context with lexical anchors, vector search, graph traversal, recency, importance, and trust signals.

Use it when an agent or a group of agents needs memory that survives across sessions, keeps provenance, and can be searched without treating recalled text as new instructions.

What it does

  • Captures agent observations, decisions, procedures, and failures as durable memory records.
  • Extracts facts and entities in the background while keeping the capture path fast.
  • Searches with BM25 lexical anchors, dense vectors, graph expansion, recency, importance, and trust-aware ranking.
  • Preserves event time and transaction time, so corrections supersede older facts instead of overwriting history.
  • Keeps namespace boundaries explicit: agent-private, team, global, and system memory are separate policy surfaces.
  • Records provenance for writes, with optional signed writes, audit signing, and quorum-gated promotion across namespaces.
  • Runs as a Rust library, a single CLI binary, or an MCP server over stdio or Streamable HTTP.

Plugins and skills

The repository ships an agent plugin at plugins/aionforge-memory that keeps memory in the task loop rather than as an afterthought. It packages small, single-sourced Agent Skills for an externally configured Aionforge Memory MCP server:

  • memory-bootstrap — one-time, idempotent cold-start setup that seeds a foundational substrate for a fresh project (identity, conventions, architecture decisions, backlog skeleton), so the next session recalls real context.
  • memory-recall — search durable memory before planning, coding, review, or release.
  • memory-capture — write decisions, facts, validation results, corrections, and handoffs as they happen.
  • work-tracking — track tasks, blockers, TODOs, and plans as durable work items (work_create → work_advance → work_link), distinct from decaying memory episodes.
  • memory-loop — use all of the above through a whole task: recall first, capture and track continuously, finish with a handoff.
  • memory-maintenance — inspect backlog, audit provenance, consolidate, forget, or restore.

The skills are plain SKILL.md Agent Skills, so the same instructions work across clients that support the format. Claude Code and Codex get the deepest integration; the plugin also includes compatibility manifests for Cursor. For Claude Code it additionally ships a default aionforge-memory-steward agent, the /aionforge-memory:memory-bootstrap, /aionforge-memory:memory-session, and /aionforge-memory:memory-handoff commands, and a SessionStart hook that re-seeds the capture/work-tracking cadence into a fresh context after a startup, resume, or context compaction.

The plugin never registers an MCP server of its own — configure the standalone aionforge-memory server separately (see docs/mcp-clients.md); the skills assume it exists. See the plugin README for install and identity details.

What it is not

Aionforge Memory is retrieval memory, not model training. It does not fine-tune a model, make the model smarter, or route work across multiple model providers. Embeddings are handled by a thin client (aionforge-embed) that talks to the OpenAI-compatible provider you configure. Consolidation is deterministic and rule-based; the substrate calls no chat/completion model.

Several subsystems are off by default and must be enabled per deployment: forgetting, read-time importance decay, cross-namespace promotion, and off-cursor note link evolution. Link evolution writes derived, non-canonical RELATES_TO edges and cannot change deterministic capture or recall for the same graph state.

The honest scope boundary is documented in docs/honest-scope.md.

MCP surface

The MCP server supports stdio and local Streamable HTTP. Put an OAuth-aware front end in front of HTTP before exposing it beyond loopback.

Read-like tools (allowed without a prompt):

  • search
  • read_memory
  • session_manifest
  • consolidation_status
  • audit_history
  • server_status
  • work_tree
  • work_query

Mutating tools (gated by the client approval policy):

  • capture
  • batch_capture
  • forget
  • unforget
  • pin
  • unpin
  • consolidate
  • work_create
  • work_advance
  • work_link

Each tool is annotated with MCP safety hints. Responses are compact receipt lines rather than large JSON payloads. Recalled memory is wrapped in a <recalled-memory-context> envelope and marked as third-party data, not instructions.

The server also publishes client setup resources such as aionforge://client/claude-code/mcp.json, with equivalents for Codex, Cursor, and OpenCode. Plugin setup guidance is available at aionforge://plugin/aionforge-memory.

Architecture

  • Storage and search: selene-db provides persistence, BM25 search, vector indexes, graph traversal, and graph algorithms.
  • Write path: capture redacts secrets, removes known prompt-injection markers, refuses residue-only captures, deduplicates cleaned content, and records provenance before derived work runs.
  • Consolidation: deterministic background passes extract facts, resolve entities, supersede stale facts, quarantine contradictions, summarize notes, and optionally induce reusable skills.
  • Retrieval: query routing chooses the relevant mix of lexical, lexical-anchor, dense, graph, recency, importance, and trust signals, then rank-fuses the results.
  • Security: namespace authorization, signed writes, audit signing, system memory exclusion, untrusted recall envelopes, cross-family guards, and red-team probes are part of the main build and CI gates.
  • Determinism: canonical capture, consolidation, and retrieval are deterministic for the same inputs and graph state. Off-cursor note link evolution stays outside that canonical path.

For the full subsystem map, see docs/README.md.

Build from source

You need the Rust toolchain pinned in rust-toolchain.toml (Rust 1.95.0, edition 2024).

Aionforge Memory depends on the public selene-db substrate, consumed from crates.io and pinned to 1.2.0. The published crates (selene-db-core, -graph, -persist, -gql, -algorithms) are aliased to stable local keys (selene-core, ...) via Cargo's package = rename, so only aionforge-store ever names them.

cargo build --workspace --locked
cargo nextest run --workspace --locked --all-features

To pull a newer selene-db 1.x release, run:

cargo update -p selene-db-core -p selene-db-graph -p selene-db-persist -p selene-db-gql -p selene-db-algorithms

For local co-development against a sibling selene-db checkout, uncomment the [patch] block at the bottom of Cargo.toml and point it at that checkout. Do not commit the uncommented form.

Set up the shared git hooks once after cloning:

bash scripts/install-hooks.sh

Run the MCP server

Start with doctor before exposing the server:

aionforge doctor
aionforge recover --json   # validates an existing WAL-backed store; does not create one

Run over stdio for a local client process:

aionforge serve stdio

serve reports the configured embedder identity to stderr at startup. When embedding is enabled, it sends one health probe and refuses to serve if the endpoint cannot return a vector with the configured dimension.

Run over local Streamable HTTP:

aionforge serve http --listen 127.0.0.1:3918

Then point your MCP client at http://127.0.0.1:3918/mcp. Keep the built-in HTTP server on loopback; put a real OAuth resource-server verifier in front of /mcp before exposing it to a shared network.

Logging and traffic

The binary logs through tracing to stderr (stdout is reserved for the MCP stdio JSON-RPC protocol and for doctor/recover reports). Logs are human-readable text by default, or structured JSON for log shippers:

aionforge serve http --log-format json     # or: AIONFORGE_LOG_FORMAT=json
RUST_LOG=aionforge_mcp=debug aionforge serve http   # standard tracing EnvFilter

--log-format is global (works on serve, doctor, recover); precedence is flag → AIONFORGE_LOG_FORMAT → default text. Level filtering is RUST_LOG (default info).

A periodic traffic heartbeat logs cumulative and per-interval bytes/tokens in (memory content captured) and out (recall responses served), every five minutes by default, with a final summary on shutdown:

INFO aionforge::traffic: memory traffic phase=heartbeat
     bytes_in_total=… bytes_out_total=… bytes_in_delta=… bytes_out_delta=…
     est_tokens_in_total=… est_tokens_out_total=… est_tokens_in_delta=… est_tokens_out_delta=…

Tune or disable the cadence with AIONFORGE_TRAFFIC_HEARTBEAT_SECS (seconds; 0 disables).

Token counts are estimates, not exact. The server cannot run the calling client's tokenizer, so est_tokens is a deliberately coarse proxy — roughly bytes ÷ 4 (≈4 characters per token). Bytes are the authoritative measure; treat tokens as an order-of-magnitude figure for capacity and cost intuition, never as an exact count or a billing source.

Logs never contain memory content, embeddings, tokens, or keys — only ids, kinds, counts, sizes, and outcomes (a CI gate enforces this). See Observability for levels, targets, span fields, and the full metrics catalog.

Run in Docker

Published images are available from GitHub Container Registry for linux/amd64 and linux/arm64:

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

Build a local image when working from source:

docker build -t aionforge-memory:dev .
docker run --rm \
  -p 127.0.0.1:3918:3918 \
  -v aionforge-data:/data \
  aionforge-memory:dev

On Apple silicon Macs running macOS 26, the published OCI image can run with Apple's container runtime. See Apple container for the local run helper and named-container persistence notes.

Persistent stores require an owner-only data directory on Unix. A fresh directory is created as 0700; an existing directory with group or other access, or a symlink, is refused. For Docker bind mounts, make the host directory owned by UID/GID 10001:10001 and mode 0700 before starting the container.

See Operations and recovery for config layering, production signing posture, backup, volume migration, and WAL-backed recovery.

Use the Rust library

Rust hosts can link the aionforge crate directly and provide an implementation of the Embedder trait. The public API re-exports the Memory facade and the domain types used in its signatures.

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())?;

// Fill CaptureRequest with the writer, namespace, role, and captured_at data
// your host already knows, then call memory.capture(request).await.
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(())
# }

See crates/aionforge/src/lib.rs and the integration tests under crates/aionforge/tests/ for complete call shapes.

Documentation

Start with:

Contributing

This project is public and pre-1.0. Issues and pull requests are welcome. Open an issue before large design changes; substantial designs are explored as RFC-style proposals first.

  • CONTRIBUTING.md — setup, the branch and release model, the commit convention, and the gate block to run before opening a PR.
  • AGENTS.md — the authoritative gate commands, crate layering, and core invariants for contributors and agents.
  • Bugs, features, and RFCs — file through the issue forms in the new-issue chooser.

Keep PR descriptions public-safe and focused on code, behavior, and validation. The repository PR template includes a public-repo check for that reason. Do not include private planning notes, internal handoff text, or agent transcripts in PR bodies.

License

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

Ver o original no GitHub

Bom para

Relacionados