Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions .env.example
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
# =============================================================================
# agentmemory configuration
# =============================================================================
#
# ======================================================================# agentmemory configuration
# ======================================================================#
# Copy this file to `~/.agentmemory/.env` (or to your project root if you
# prefer scoped config) and uncomment the lines you want to override.
#
Expand Down Expand Up @@ -225,6 +223,10 @@
# AGENTMEMORY_BINDINGS=auto # bindings mode for HTTP routes and state events: auto (observe when supported), observe, trigger
# AGENTMEMORY_STATE_READY_TIMEOUT_MS=60000 # max wait for the state probe reported as runtime.stateWorker in /status (1000-600000)
# AGENTMEMORY_ROUTE_MAX_IN_FLIGHT=1024 # max concurrent requests per observer-bound route (1-65536)
# AGENTMEMORY_COMPRESS_MAX_CONCURRENT=2 # max concurrent LLM compressions via the capture observer (1-32)
# AGENTMEMORY_COMPRESSION_SWEEP_MS=600000 # pending-compression recovery sweep interval; 0 disables (0 or 60000-86400000)
# AGENTMEMORY_GRAPH_EXTRACT_COOLDOWN_MS=0 # min ms between per-session graph extractions (0-86400000; 0 = no cooldown)
# AGENTMEMORY_GRAPH_STRUCTURAL=true # heuristic/structural graph pass; false leaves only the LLM pass

# Engine usage telemetry (iii). Off unless you set it; true opts in.
# III_TELEMETRY_ENABLED=false
Expand Down
4 changes: 4 additions & 0 deletions deploy/coolify/docker-compose.yml
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,10 @@ services:
AGENTMEMORY_BINDINGS: "${AGENTMEMORY_BINDINGS:-}"
AGENTMEMORY_STATE_READY_TIMEOUT_MS: "${AGENTMEMORY_STATE_READY_TIMEOUT_MS:-}"
AGENTMEMORY_ROUTE_MAX_IN_FLIGHT: "${AGENTMEMORY_ROUTE_MAX_IN_FLIGHT:-}"
AGENTMEMORY_COMPRESS_MAX_CONCURRENT: "${AGENTMEMORY_COMPRESS_MAX_CONCURRENT:-}"
AGENTMEMORY_COMPRESSION_SWEEP_MS: "${AGENTMEMORY_COMPRESSION_SWEEP_MS:-}"
AGENTMEMORY_GRAPH_EXTRACT_COOLDOWN_MS: "${AGENTMEMORY_GRAPH_EXTRACT_COOLDOWN_MS:-}"
AGENTMEMORY_GRAPH_STRUCTURAL: "${AGENTMEMORY_GRAPH_STRUCTURAL:-}"
AGENTMEMORY_SECRET: "${AGENTMEMORY_SECRET:-}"
AGENT_ID: "${AGENT_ID:-}"
TEAM_ID: "${TEAM_ID:-}"
Expand Down
4 changes: 4 additions & 0 deletions deploy/runtime/worker-compose.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,10 @@ containers:
AGENTMEMORY_BINDINGS: "${AGENTMEMORY_BINDINGS:-}"
AGENTMEMORY_STATE_READY_TIMEOUT_MS: "${AGENTMEMORY_STATE_READY_TIMEOUT_MS:-}"
AGENTMEMORY_ROUTE_MAX_IN_FLIGHT: "${AGENTMEMORY_ROUTE_MAX_IN_FLIGHT:-}"
AGENTMEMORY_COMPRESS_MAX_CONCURRENT: "${AGENTMEMORY_COMPRESS_MAX_CONCURRENT:-}"
AGENTMEMORY_COMPRESSION_SWEEP_MS: "${AGENTMEMORY_COMPRESSION_SWEEP_MS:-}"
AGENTMEMORY_GRAPH_EXTRACT_COOLDOWN_MS: "${AGENTMEMORY_GRAPH_EXTRACT_COOLDOWN_MS:-}"
AGENTMEMORY_GRAPH_STRUCTURAL: "${AGENTMEMORY_GRAPH_STRUCTURAL:-}"
AGENTMEMORY_SECRET: "${AGENTMEMORY_SECRET:-}"
AGENT_ID: "${AGENT_ID:-}"
TEAM_ID: "${TEAM_ID:-}"
Expand Down
4 changes: 4 additions & 0 deletions docker-compose.yml
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,10 @@ services:
AGENTMEMORY_BINDINGS: "${AGENTMEMORY_BINDINGS:-}"
AGENTMEMORY_STATE_READY_TIMEOUT_MS: "${AGENTMEMORY_STATE_READY_TIMEOUT_MS:-}"
AGENTMEMORY_ROUTE_MAX_IN_FLIGHT: "${AGENTMEMORY_ROUTE_MAX_IN_FLIGHT:-}"
AGENTMEMORY_COMPRESS_MAX_CONCURRENT: "${AGENTMEMORY_COMPRESS_MAX_CONCURRENT:-}"
AGENTMEMORY_COMPRESSION_SWEEP_MS: "${AGENTMEMORY_COMPRESSION_SWEEP_MS:-}"
AGENTMEMORY_GRAPH_EXTRACT_COOLDOWN_MS: "${AGENTMEMORY_GRAPH_EXTRACT_COOLDOWN_MS:-}"
AGENTMEMORY_GRAPH_STRUCTURAL: "${AGENTMEMORY_GRAPH_STRUCTURAL:-}"
AGENTMEMORY_SECRET: "${AGENTMEMORY_SECRET:-}"
AGENT_ID: "${AGENT_ID:-}"
TEAM_ID: "${TEAM_ID:-}"
Expand Down
4 changes: 4 additions & 0 deletions docs/upgrades/iii-0.25.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,10 @@ Existing file state remains at `state_store.db`; this upgrade does not convert o
- The viewer remains on port 3113 by default. Live updates use authenticated SSE at `/agentmemory/viewer/events` on the REST port. Port 3112 is no longer used.
- `/agentmemory/status` reports the configured engine pin as `service.enginePinnedVersion`, replacing the old `engineVersion` field. This is the supported version, not a probe of an arbitrary remote engine.
- HTTP routes and state subscriptions are bound through `src/runtime/bindings.ts` (`getBindings(sdk).http/.state`). In `auto` mode (default) agentmemory attaches native observers to `http::on-request` and `state::on-changed` when the providers advertise them, and falls back to `registerTrigger` otherwise. `AGENTMEMORY_BINDINGS=observe|trigger` forces a mode. `AGENTMEMORY_STATE_READY_TIMEOUT_MS` (1000-600000, default 60000) bounds the state-worker readiness probe before boot reads; late arrival is covered by event-driven re-arm. `AGENTMEMORY_ROUTE_MAX_IN_FLIGHT` (1-65536, default 1024) bounds concurrent deliveries per observer-bound route.

### Background work runs through observers

With `AGENTMEMORY_BINDINGS` unset or `auto` (and an SDK that supports `observe`), background work is dispatched by engine observers instead of inline fire-and-forget triggers: per-observation LLM compression follows `mem::observe` output (`agentmemory:pipeline:compress-on-capture`, bounded by `AGENTMEMORY_COMPRESS_MAX_CONCURRENT`, default 2), post-session graph extraction/reflection/consolidation follow `event::session::stopped`, and graph extraction on `mem::remember` is observe-only. `AGENTMEMORY_COMPRESSION_SWEEP_MS` (default 600000, 0 disables) runs a recovery sweep for observations still pending compression. `AGENTMEMORY_GRAPH_EXTRACT_COOLDOWN_MS` (default 0) rate-limits per-session delta extraction, `AGENTMEMORY_GRAPH_STRUCTURAL=false` disables the heuristic graph pass (LLM pass only), and per-session markers in `mem:graph:extract-marks` dedupe extraction to new observations only. In `trigger` mode the existing inline fan-out is unchanged.
- iii 0.25 can dispatch calls to a worker's own functions locally. Engine-side spans differ for those calls; SDK tracing and state-worker persistence still apply.
- Local dispatch is on by default, so AgentMemory's internal calls to its own functions run in-process and produce only the SDK's execute span, not an engine call span. Set `AGENTMEMORY_LOCAL_DISPATCH=false` for full engine traces at the cost of a round trip per call.

Expand Down
6 changes: 5 additions & 1 deletion plugin/skills/agentmemory-config/REFERENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
Generated by scanning `src/` for `AGENTMEMORY_*` usage. Do not edit the block below by hand; run `npm run skills:gen` after adding or removing a variable. Internal markers ending in two underscores are excluded.

<!-- AUTOGEN:env START - generated by scripts/skills/generate.ts, do not edit by hand -->
Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 84 recognized variables:
Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 88 recognized variables:

- `AGENTMEMORY_AGENT_SCOPE`
- `AGENTMEMORY_ALLOW_AGENT_SDK`
Expand All @@ -28,6 +28,8 @@ Configuration is read from the environment and from `~/.agentmemory/.env` (no `e
- `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS`
- `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES`
- `AGENTMEMORY_COMMIT_SHA`
- `AGENTMEMORY_COMPRESSION_SWEEP_MS`
- `AGENTMEMORY_COMPRESS_MAX_CONCURRENT`
- `AGENTMEMORY_CONSOLIDATION_COOLDOWN_MS`
- `AGENTMEMORY_COPILOT_MCP_BLOCK`
- `AGENTMEMORY_CREDENTIAL_MODE`
Expand All @@ -45,6 +47,8 @@ Configuration is read from the environment and from `~/.agentmemory/.env` (no `e
- `AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS`
- `AGENTMEMORY_FORCE_PROXY`
- `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT`
- `AGENTMEMORY_GRAPH_EXTRACT_COOLDOWN_MS`
- `AGENTMEMORY_GRAPH_STRUCTURAL`
- `AGENTMEMORY_GRAPH_WEIGHT`
- `AGENTMEMORY_III_VERSION`
- `AGENTMEMORY_IMAGE_EMBEDDINGS`
Expand Down
6 changes: 3 additions & 3 deletions scripts/docs-sync.state.json
Original file line number Diff line number Diff line change
Expand Up @@ -23,16 +23,16 @@
"4600+"
],
"functions": [
"323"
"328"
],
"sourceFiles": [
"263"
"266"
],
"loc": [
"61000"
],
"kvScopes": [
"65"
"66"
]
},
"engineVersion": "0.25.1"
Expand Down
4 changes: 4 additions & 0 deletions src/cli/compose-project.ts
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,10 @@ const AGENTMEMORY_WORKER_ENV_ALLOWLIST = new Set([
"AGENTMEMORY_BINDINGS",
"AGENTMEMORY_STATE_READY_TIMEOUT_MS",
"AGENTMEMORY_ROUTE_MAX_IN_FLIGHT",
"AGENTMEMORY_COMPRESS_MAX_CONCURRENT",
"AGENTMEMORY_COMPRESSION_SWEEP_MS",
"AGENTMEMORY_GRAPH_EXTRACT_COOLDOWN_MS",
"AGENTMEMORY_GRAPH_STRUCTURAL",
]);

const COMPOSE_RESERVED_ENV = new Set([
Expand Down
29 changes: 29 additions & 0 deletions src/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -557,6 +557,35 @@ export function isAutoCompressEnabled(): boolean {
return getMergedEnv()["AGENTMEMORY_AUTO_COMPRESS"] === "true";
}

export function compressMaxConcurrent(): number {
const raw = getMergedEnv()["AGENTMEMORY_COMPRESS_MAX_CONCURRENT"];
if (raw === undefined) return 2;
const parsed = Number(raw);
if (!Number.isInteger(parsed) || parsed < 1 || parsed > 32) return 2;
return parsed;
}

export function compressionSweepMs(): number {
const raw = getMergedEnv()["AGENTMEMORY_COMPRESSION_SWEEP_MS"];
if (raw === undefined) return 600_000;
const parsed = Number(raw);
if (parsed === 0) return 0;
if (!Number.isInteger(parsed) || parsed < 60_000 || parsed > 86_400_000) return 600_000;
return parsed;
}

export function graphExtractCooldownMs(): number {
const raw = getMergedEnv()["AGENTMEMORY_GRAPH_EXTRACT_COOLDOWN_MS"];
if (raw === undefined) return 0;
const parsed = Number(raw);
if (!Number.isInteger(parsed) || parsed < 0 || parsed > 86_400_000) return 0;
return parsed;
}

export function isGraphStructuralEnabled(): boolean {
return getMergedEnv()["AGENTMEMORY_GRAPH_STRUCTURAL"] !== "false";
}

// Hook-level context injection into Claude Code's conversation is OFF by
// default as of 0.8.10. When disabled, pre-tool-use and
// session-start hooks still POST observations for background capture, but
Expand Down
59 changes: 59 additions & 0 deletions src/functions/compression-sweep.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
import type { IIIClient } from "iii-sdk";
import type { StateKV } from "../state/kv.js";
import { collectAll } from "../state/kv.js";
import { KV } from "../state/schema.js";
import type { CompressedObservation, Session } from "../types.js";
import { compressMaxConcurrent, isAutoCompressEnabled } from "../config.js";
import { needsCompression } from "./compression-state.js";
import { logger } from "../logger.js";
import { singleFlight } from "../runtime/recovery.js";

const MAX_AGE_MS = 5 * 60_000;
const MAX_PER_RUN = 50;

export function createCompressionSweep(sdk: IIIClient, kv: StateKV) {
return singleFlight(async () => {
const candidates: Array<{ sessionId: string; observationId: string }> = [];
const cutoff = Date.now() - MAX_AGE_MS;
const sessions = await kv.list<Session>(KV.sessions);
for (const session of sessions) {
const observations = await collectAll<CompressedObservation>(kv, KV.observations(session.id));
for (const obs of observations) {
if (candidates.length >= MAX_PER_RUN) break;
if (!needsCompression(obs)) continue;
if (Date.parse(obs.timestamp) > cutoff) continue;
candidates.push({ sessionId: session.id, observationId: obs.id });
}
if (candidates.length >= MAX_PER_RUN) break;
}
const concurrency = Math.min(compressMaxConcurrent(), Math.max(1, candidates.length));
let inFlight = 0;
let dispatched = 0;
await new Promise<void>((resolve) => {
const next = () => {
while (inFlight < concurrency && dispatched < candidates.length) {
const c = candidates[dispatched++];
inFlight++;
sdk.trigger({ function_id: "mem::compress", payload: c })
.catch(() => {})
.finally(() => { inFlight--; if (dispatched >= candidates.length && inFlight === 0) resolve(); else next(); });
}
if (dispatched >= candidates.length && inFlight === 0) resolve();
};
next();
if (candidates.length === 0) resolve();
});
if (candidates.length > 0) logger.info("Compression sweep dispatched stale observations", { count: candidates.length });
return { dispatched: candidates.length };
});
}

export function registerCompressionSweepFunction(sdk: IIIClient, kv: StateKV): () => Promise<{ dispatched: number }> {
const run = createCompressionSweep(sdk, kv);
sdk.registerFunction("mem::compression-sweep", () => run());
return run;
}

export function compressionSweepEnabled(): boolean {
return isAutoCompressEnabled();
}
20 changes: 11 additions & 9 deletions src/functions/graph.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ import {
GRAPH_EXTRACTION_SYSTEM,
buildGraphExtractionPrompt,
} from "../prompts/graph-extraction.js";
import { isGraphExtractionEnabled } from "../config.js";
import { isGraphExtractionEnabled, isGraphStructuralEnabled } from "../config.js";
import { recordAudit, safeAudit } from "./audit.js";
import { logger } from "../logger.js";
import { scrubRecord } from "./privacy.js";
Expand Down Expand Up @@ -730,14 +730,16 @@ export function registerGraphFunction(

let nodes: GraphNode[] = [];
let edges: GraphEdge[] = [];
try {
const heuristic = extractGraphHeuristics(data.observations);
nodes = heuristic.nodes;
edges = heuristic.edges;
} catch (err) {
logger.warn("heuristic graph extraction failed", {
error: err instanceof Error ? err.message : String(err),
});
if (isGraphStructuralEnabled()) {
try {
const heuristic = extractGraphHeuristics(data.observations);
nodes = heuristic.nodes;
edges = heuristic.edges;
} catch (err) {
logger.warn("heuristic graph extraction failed", {
error: err instanceof Error ? err.message : String(err),
});
}
}

const llmEnabled =
Expand Down
5 changes: 3 additions & 2 deletions src/functions/observe.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ import { indexObservationSession } from "../state/obs-index.js";
import { scrubRecord } from "./privacy.js";
import { DedupMap, recordDedupSkip } from "./dedup.js";
import { afterKeyedLock, withKeyedLock } from "../state/keyed-mutex.js";
import { getBindings } from "../runtime/bindings.js";
import { getFinalizeIdleMs, isAutoCompressEnabled } from "../config.js";
import { buildSyntheticCompression } from "./compress-synthetic.js";
import { isCaptureKey } from "../capture/event-record.js";
Expand Down Expand Up @@ -388,7 +389,7 @@ export function registerObserveFunction(
},
});

if (autoCompress) {
if (autoCompress && getBindings(sdk).pipeline !== "observe") {
afterKeyedLock(`obs:${payload.sessionId}`, async () => {
try {
await sdk.trigger({
Expand All @@ -408,7 +409,7 @@ export function registerObserveFunction(
hook: payload.hookType,
compress: autoCompress ? "llm" : "synthetic",
});
return { observationId: obsId };
return { observationId: obsId, sessionId: payload.sessionId };
});
},
);
Expand Down
87 changes: 87 additions & 0 deletions src/functions/post-session.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
import type { IIIClient } from "iii-sdk";
import { TriggerAction } from "iii-sdk";
import type { StateKV } from "../state/kv.js";
import { collectAll } from "../state/kv.js";
import { KV } from "../state/schema.js";
import type { CompressedObservation, GraphExtractMark, Memory } from "../types.js";
import { graphExtractCooldownMs, isConsolidationEnabled, detectLlmProviderKind } from "../config.js";
import { isReflectEnabled } from "./slots.js";
import { logger } from "../logger.js";
import { consolidationDue } from "../triggers/events.js";
import { getGraphGeneration } from "../state/graph-generation.js";

const graphStamp = (o: CompressedObservation): string => o.compressedAt ?? o.timestamp;

const fireVoid = (sdk: IIIClient, function_id: string, payload: unknown, sessionId: string) =>
sdk
.trigger({ function_id, payload, action: TriggerAction.Void() })
.catch((err) =>
logger.warn(function_id + " trigger failed", {
sessionId,
error: err instanceof Error ? err.message : String(err),
}),
);

export function registerPostSessionFunctions(sdk: IIIClient, kv: StateKV): void {
sdk.registerFunction("mem::post-session-graph", async (data: { sessionId: string }) => {
const stored = await kv.get<GraphExtractMark>(KV.graphExtractMarks, data.sessionId);
const graphGeneration = await getGraphGeneration(kv);
const marker = stored && (stored.graphGeneration ?? null) === graphGeneration ? stored : null;
const cooldownMs = graphExtractCooldownMs();
if (marker && cooldownMs > 0 && Date.now() - Date.parse(marker.updatedAt) < cooldownMs) {
return { skipped: "cooldown", updatedAt: marker.updatedAt };
}
const since = marker ? Date.parse(marker.lastObservationTimestamp) : 0;
const observations = await collectAll<CompressedObservation>(kv, KV.observations(data.sessionId));
const fresh = observations.filter((o) => o.title && Date.parse(graphStamp(o)) > since);
if (fresh.length === 0) return { extracted: 0 };
const result = await sdk.trigger<{ observations: CompressedObservation[] }, { success?: boolean; error?: string } | null>({
function_id: "mem::graph-extract",
payload: { observations: fresh },
});
if (result?.success === false) return { extracted: 0, error: result.error ?? "graph extraction failed" };
const maxTs = fresh.reduce((max, o) => (graphStamp(o) > max ? graphStamp(o) : max), marker?.lastObservationTimestamp ?? "");
await kv.set(KV.graphExtractMarks, data.sessionId, {
sessionId: data.sessionId,
lastObservationTimestamp: maxTs,
extractedCount: (marker?.extractedCount ?? 0) + fresh.length,
updatedAt: new Date().toISOString(),
graphGeneration,
} satisfies GraphExtractMark);
return { extracted: fresh.length };
});

sdk.registerFunction("mem::post-session-reflect", async (data: { sessionId: string }) => {
if (!isReflectEnabled()) return { skipped: "reflect_disabled" };
return sdk.trigger({ function_id: "mem::slot-reflect", payload: { sessionId: data.sessionId } });
});

sdk.registerFunction("mem::post-session-consolidate", async (data: { sessionId: string; skipConsolidation?: boolean }) => {
if (!isConsolidationEnabled()) return { skipped: "consolidation_disabled" };
if (!(await consolidationDue(kv))) return { skipped: "debounced" };
fireVoid(sdk, "mem::consolidate-pipeline", { tier: "all", force: true }, data.sessionId);
fireVoid(sdk, "mem::auto-crystallize", { olderThanDays: 0 }, data.sessionId);
if (detectLlmProviderKind() === "llm") {
fireVoid(sdk, "mem::skill-extract", { sessionId: data.sessionId }, data.sessionId);
}
return { fired: true };
});

sdk.registerFunction("mem::post-remember-graph", async (data: { input?: { content?: string; type?: string; concepts?: string[] }; output?: { success?: boolean; memory?: Memory } }) => {
const memory = data.output?.memory;
if (!data.output?.success || !memory) return { skipped: "no_memory" };
const content = typeof data.input?.content === "string" ? data.input.content : "";
const observation = {
id: memory.id,
title: memory.title || content.slice(0, 120) || memory.type,
narrative: content,
type: "compressed_observation",
timestamp: memory.createdAt,
sessionId: `memory:${memory.id}`,
hookType: "remember",
concepts: data.input?.concepts ?? memory.concepts ?? [],
files: memory.files ?? [],
} as unknown as CompressedObservation;
Comment thread
rohitg00 marked this conversation as resolved.
Resolved
return sdk.trigger({ function_id: "mem::graph-extract", payload: { observations: [observation] } });
});
}
Loading