ActiveGraph

ActiveGraph gives agents an append-only event chain. ZMem can persist useful events as local memory, retain the causal event id, and write compact benchmark traces that stay replayable without one receipt bundle per question.

Install And Verify

ActiveGraph discovers packs through Python entry points. Install the optional integration in the same environment as ActiveGraph:

python -m pip install -e '.[activegraph]'
activegraph pack list
python scripts/verify_activegraph_pack.py --summary-only
python examples/activegraph_host.py --summary-only

Expected result:

ActiveGraph pack verify: PASS
Failed checks: none

The verifier uses ActiveGraph's real discovery and runtime APIs. It checks the zerker_memory.pack:pack entry point, idempotent loading, pack.loaded, both canonical behaviors, an actual object.created event persisted into ZMem, and a model call whose ZMem-enriched prompt exactly matches the recorded llm.requested prompt.

Runtime Behaviors

zmem.persist

The installed pack listens for:

• object.created
• patch.applied
• llm.responded
• tool.responded
• policy.created
• relation.created

The behavior writes to the real ZMem store under ag:{run_id} by default and records caused_by_event so the memory points back to the ActiveGraph event that produced it.

zmem.recall

The source adapter's recall() function returns a prepend_context payload for hosts that invoke it before a model call. Retrieval is selected with fts, semantic, or hybrid.

For ActiveGraph LLM behaviors, wrap the behavior once before constructing the runtime:

from pathlib import Path

from zerker_memory.integrations.activegraph import enable_precall_recall

enable_precall_recall(
    answer_question,
    db_path=Path(".zerker/memory.sqlite"),
    retrieval_mode="fts",
)

enable_precall_recall(...) enriches the prompt before ActiveGraph hashes it, emits llm.requested, and calls the provider. The verifier confirms that the provider-bound message and the event-recorded message are identical.

The installed zmem.recall behavior on supported ActiveGraph runtimes still observes the immutable llm.requested event and records the corresponding local read receipt. It is an audit hook, not a second prompt mutation path.

Run The Two-Run Host

The runnable host uses no API key or hosted model. Its first ActiveGraph run loads the installed pack and persists an object event into ZMem. A distinct resume run recalls that memory before its model call through a deterministic local provider.

python examples/activegraph_host.py --summary-only

Expected result:

ActiveGraph host example: PASS
Runs: zmem-activegraph-host -> zmem-activegraph-host-resume
Recorded prompt matches provider: yes
Answer: The release target is Production.
Failed checks: none

Use --db, --session, or --retrieval-mode to isolate the local store, choose the shared session scope, or compare fts, semantic, and hybrid recall. The command exits nonzero if persistence, causal lineage, recall, receipt attachment, prompt equality, or the memory-derived answer fails.

Typed Pack

The loader entry point resolves to a concrete ActiveGraph Pack object:

name: zmem
version: "0.1.17"
entry_point: zerker_memory.pack:pack
behaviors:
  - zmem.persist
  - zmem.recall
config:
  ZMEM_RETRIEVAL_MODE:
    default: "fts"
  ZMEM_TREESHIP_ENABLED:
    default: "false"

The benchmark's four reactive stage names remain runner stages, not fake runtime pack behaviors.

Compact Benchmark Runner

zmem-bench-locomo writes:

• activegraph.sqlite, the causal event log;
• memory.sqlite, the actual local memory store;
• trace.jsonl, one compact proof line per question;
• scored_receipt.json, aggregate hashes and run metadata;
• zero per-question receipt bundles.

zmem-bench-locomo \
  --dataset data/locomo/locomo_official_zmem.json \
  --out .zerker/bench/activegraph \
  --run-id "activegraph-$(date -u +%Y%m%dT%H%M%SZ)" \
  --retrieval-mode fts-adaptive \
  --split default \
  --event-batch-size 128

The runner uses WAL, commits events in bounded batches, ingests each conversation once, and stores compact retrieval summaries instead of copying the complete receipt into every event.

Verified Acceptance

The v0.1.4 acceptance run used the stable 227-question cohort:

• 227 questions across 10 conversations;
• 5,882 local memories;
• 908 replayable ActiveGraph events;
• 8 event-log commits at batch size 128;
• 1 MB activegraph.sqlite;
• 196 KB trace.jsonl;
• zero *.bundle.json files.

This proves loader compatibility, event durability, and bounded trace storage. The runner's simple deterministic answerer is not an official LoCoMo quality score.