Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
37 commits
Select commit Hold shift + click to select a range
cfd3bad
feat: harden session context and workstation tool surface
wrightpt Jul 10, 2026
ea07760
fix: preserve session activity time during context migration
wrightpt Jul 10, 2026
029ca6d
feat: expose deployment source revision in health
wrightpt Jul 10, 2026
bbdb802
fix: keep viewer stream updates transient
wrightpt Jul 10, 2026
bb18f80
Merge pull request #1 from wrightpt/fix/viewer-stream-write-amplifica…
wrightpt Jul 10, 2026
d4a32ce
fix action list pagination
wrightpt Jul 10, 2026
53fdc26
Merge pull request #2 from wrightpt/agent/action-export-pagination
wrightpt Jul 10, 2026
2a443c6
chore add AgentMemory project scope
wrightpt Jul 10, 2026
acb9be8
Merge pull request #3 from wrightpt/agent/repo-identity
wrightpt Jul 10, 2026
8e5ad1f
Decouple hook capture from synchronous observe
wrightpt Jul 13, 2026
77014dc
Merge pull request #4 from wrightpt/agent/async-observe-ingest
wrightpt Jul 14, 2026
909ae07
Await asynchronous hook transport acknowledgements
wrightpt Jul 14, 2026
62eb3a3
Merge pull request #5 from wrightpt/agent/await-observe-ack
wrightpt Jul 14, 2026
1597995
fix: make observation ingestion durable
wrightpt Jul 14, 2026
2fa853b
Merge pull request #6 from wrightpt/agent/durable-observation-queue
wrightpt Jul 14, 2026
3175343
build: rebuild runtime before npm pack
wrightpt Jul 14, 2026
f0e1e64
Merge pull request #7 from wrightpt/agent/reliable-package-build
wrightpt Jul 14, 2026
87fda32
fix: prevent duplicate worker registration
wrightpt Jul 14, 2026
b88c00f
Merge pull request #8 from wrightpt/agent/worker-singleton-guard
wrightpt Jul 14, 2026
073bf47
feat: add stateless Streamable HTTP MCP transport
wrightpt Jul 14, 2026
32b1ad8
Merge pull request #9 from wrightpt/agent/streamable-http-mcp-v1
wrightpt Jul 14, 2026
26b5062
fix invocation bookkeeping leak
wrightpt Jul 16, 2026
2e0b8e6
chore: refresh generated skill reference
wrightpt Jul 16, 2026
2f17da8
fix hooks: bound project scope traversal
wrightpt Jul 16, 2026
65b233c
chore: refresh generated hook scripts
wrightpt Jul 16, 2026
52fb63c
test: compare canonical project paths
wrightpt Jul 16, 2026
c4bc638
Merge pull request #10 from wrightpt/fix/iii-void-invocation-leak
wrightpt Jul 16, 2026
27b2eee
fix(actions): exclude blocked work from frontier
wrightpt Jul 17, 2026
9e18085
Merge pull request #11 from wrightpt/agent/exclude-blocked-actions
wrightpt Jul 17, 2026
fb10d2f
feat: add Actions v2 schema and migration
wrightpt Jul 17, 2026
6698634
fix: harden Actions v2 migration invariants
wrightpt Jul 17, 2026
adcc99d
Merge pull request #12 from wrightpt/agent/actions-v2-schema-migration
wrightpt Jul 17, 2026
917ce1e
fix(actions): compare normalized rows semantically
wrightpt Jul 17, 2026
5f81d4e
fix(actions): coerce undefined state::get results to null at the Stat…
wrightpt Jul 17, 2026
b56bf7a
docs: record iii-engine state semantics and workstation deploy path
wrightpt Jul 18, 2026
2fbf40b
feat(actions): add mem::action-gc terminal-action pruning
wrightpt Jul 18, 2026
4fd62a0
ci: retire push/PR triggers to workflow_dispatch (local-builds quota …
wrightpt Jul 28, 2026
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
12 changes: 12 additions & 0 deletions .agentmemory/project.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
{
"project_id": "agentmemory",
"scope_type": "repo",
"repo_root": "/home/cp/repos/agent-infra/agentmemory",
"memory_policy": "default-isolated",
"related_projects": [
"workstation",
"agent-workspace-config",
"agent-skills",
"repo-brain"
]
}
6 changes: 6 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,7 @@
# -----------------------------------------------------------------------------

# AGENTMEMORY_AUTO_COMPRESS=true # Run LLM compression on every observation batch (requires a provider key). Default off — synthetic compression handles most cases.
# AGENTMEMORY_DISABLE_LLM_TOOLS=true # Disable LLM-backed execution. Calls return skipped_disabled and increment skippedCount instead of failureCount.
# AGENTMEMORY_INJECT_CONTEXT=true # Inject recalled memories back into agent prompts (#143). Default off — hooks capture observations but do not modify conversation.
# CONSOLIDATION_ENABLED=true # Run the 4-tier consolidation pipeline (memories → semantic → procedural). Default off — opt in once you've measured the LLM cost.
# CONSOLIDATION_DECAY_DAYS=30 # Age (days) after which non-reinforced memories decay during consolidation
Expand All @@ -127,6 +128,11 @@
# AGENTMEMORY_URL=http://localhost:3111 # REST base URL — honored by status, doctor, MCP shim
# AGENTMEMORY_VIEWER_URL=http://localhost:3113 # Override the viewer URL printed by `agentmemory status`
# AGENTMEMORY_EXPORT_ROOT=~/agentmemory-backup # Default destination for `agentmemory export`
# AGENTMEMORY_MCP_HTTP_HOST=127.0.0.1 # Streamable HTTP MCP bind host
# AGENTMEMORY_MCP_HTTP_PORT=3114 # Streamable HTTP MCP port
# AGENTMEMORY_MCP_HTTP_TOKEN=your-secret # Optional bearer token for the MCP listener
# AGENTMEMORY_MCP_HTTP_ALLOWED_ORIGINS=http://127.0.0.1:7681 # Extra comma-separated browser origins
# AGENTMEMORY_MCP_HTTP_ALLOW_REMOTE=1 # Required with a bearer token for non-loopback binds

# STANDALONE_MCP=1 # MCP shim only — bypass the worker and run @agentmemory/mcp in-process
# STANDALONE_PERSIST_PATH=~/.agentmemory/local.db # Path used by the standalone MCP shim's local fallback store
Expand Down
34 changes: 5 additions & 29 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -1,35 +1,11 @@
name: CI

# `paths-ignore` keeps doc-only / website / README / CHANGELOG churn from
# burning runner minutes. Source / config / workflow changes always run.
# `workflow_dispatch` gives a manual re-run button for flake debugging.
# Retired to workflow_dispatch-only (2026-07-28): the GitHub account has a
# 2,000-min/month Actions quota with a $0 stop-usage budget, so push/PR
# triggers were removed (fleet local-builds policy). Run `npm test` locally
# before PR (see AGENTS.md); dispatch manually from the Actions tab when a
# hosted run is genuinely needed.
on:
push:
branches: [main]
paths-ignore:
- "README.md"
- "CHANGELOG.md"
- "AGENTS.md"
- "ROADMAP.md"
- "website/**"
- "docs/**"
- "assets/**"
- "deploy/**/README.md"
- "**/*.md"
- "**/*.mdx"
pull_request:
branches: [main]
paths-ignore:
- "README.md"
- "CHANGELOG.md"
- "AGENTS.md"
- "ROADMAP.md"
- "website/**"
- "docs/**"
- "assets/**"
- "deploy/**/README.md"
- "**/*.md"
- "**/*.mdx"
workflow_dispatch:

# Cancel in-flight PR runs when a force-push lands. Keep push runs to
Expand Down
28 changes: 23 additions & 5 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,17 @@ agentmemory is a persistent memory system for AI coding agents, built on iii-eng
- **Build**: TypeScript → ESM via tsdown, output to `dist/`
- **Test**: vitest (`npm test` excludes integration tests)

## Consistency Rules
## iii-engine State Semantics

- `state::get` resolves **`undefined`** (absent result field) for missing keys or scopes — not `null`. `StateKV.get` normalizes this to `null` (`value ?? null`), so `T | null` is the guaranteed contract everywhere downstream; never bypass `StateKV` to call `state::get` directly, and never compare store results with strict `=== null` upstream of it. (2026-07-17: this gap made every `mem::action-create` throw `action_revision_conflict` while updates kept working.)
- `state::list` returns `[]` for missing scopes; `state::update` reports `old_value: null`; `state::delete` returns `{}`. Only `get` has the undefined gap (probed live 2026-07-17).
- In-memory test mocks (`test/helpers/mocks.ts`) return `null` because that is the `StateKV` contract. Engine-faithful boundary coverage (undefined-returning trigger) lives in `test/state-kv.test.ts` — add new `state::*` semantics probes there.

## Workstation Deployment

On the workstation the global package (`npm ls -g @agentmemory/agentmemory`) is a **symlink to this repo's checkout**, so a deploy is: `npm run build`, then `systemctl --user restart agentmemory.service`. The health sentinel (`agentmemory_health_sentinel.sh`, 15-min timer) verifies the running buildId/source revision against `agent-workspace-config/agentmemory-lock.json` and canaries the actions write path every run.

## Consistency Rules
**When adding or removing MCP tools, you MUST update ALL of the following:**
1. `src/mcp/tools-registry.ts` — tool definition + `getAllTools()` array
2. `src/mcp/server.ts` — handler case in the `mcp::tools::call` switch
Expand Down Expand Up @@ -57,6 +66,14 @@ sdk.registerFunction(
);
```

### Detached Function Calls

While `iii-sdk` is pinned to 0.11.2, do not use `TriggerAction.Void()`. That
engine path adds a generated ID to the worker's active invocation set, while
the SDK deliberately sends no `InvocationResult` that could remove it. Use
`triggerDetached()` from `src/utils/trigger-detached.ts` for non-blocking work;
use a normal awaited `sdk.trigger()` when the caller needs the result.

### REST Endpoint Registration
```typescript
sdk.registerFunction("api::your-endpoint", async (req: ApiRequest) => {
Expand Down Expand Up @@ -94,7 +111,8 @@ case "memory_your_tool": {
Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). They read JSON from stdin, make HTTP calls to the REST API, and exit. There are two patterns depending on whether Claude Code consumes the script's stdout:

- **Context-injecting hooks** (`pre-tool-use`, `pre-compact`, `session-start`) write recalled context to stdout for Claude Code to inject. These MUST use `try/catch` with `await fetch(..., { signal: AbortSignal.timeout(N) })` — the script has to wait for the response before exiting, and the timeout is the only bound on hang time.
- **Telemetry-only hooks** (`notification`, `post-tool-failure`, `post-tool-use`, `prompt-submit`, `stop`, `session-end`, `subagent-start`, `subagent-stop`, `task-completed`) write nothing to stdout. These MUST use fire-and-forget `fetch(..., { signal: AbortSignal.timeout(N) }).catch(() => {})` paired with `setTimeout(() => process.exit(0), 500).unref()`. The unawaited fetch dispatches the request; the unref'd `setTimeout` force-exits the process after the request has been flushed to the local daemon's socket buffer (~500ms is enough for single-request hooks; use 1500ms for multi-request hooks like `stop` and `session-end` so all fetches have time to start, especially when `AGENTMEMORY_URL` points to a remote daemon). Without the `setTimeout` Node keeps the event loop alive waiting for any in-flight fetch to settle, which means the hook still blocks Claude Code's next-prompt boundary for up to the AbortSignal duration — exactly the bug fire-and-forget is meant to fix.
- **Observation telemetry hooks** (`notification`, `post-tool-failure`, `post-tool-use`, `prompt-submit`, `subagent-start`, `subagent-stop`, `task-completed`) MUST call and await the shared `submitObservation()` helper. The REST endpoint returns `202` only after iii's file-backed `agentmemory-observations` queue returns a receipt, so this waits for durable acceptance rather than full persistence/indexing. The helper's bounded timeout defaults to 500ms and failures stay silent. Do not reintroduce unawaited `fetch()` plus hard `process.exit()`: terminating the client before the response lifecycle completes can strand iii invocation bookkeeping.
- **Multi-request telemetry hooks** (`stop`, `session-end`) still use fire-and-forget requests with a 1500ms exit bound because they dispatch several independent lifecycle calls, not only the asynchronous observation endpoint.

## Coding Standards

Expand All @@ -114,10 +132,10 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import).
- Test files go in `test/` with `.test.ts` extension
- Follow existing patterns in `test/crystallize.test.ts` for function tests

## Current Stats (v0.9.16)
## Current Stats (v0.9.27)

- 53 MCP tools (8 visible by default, `AGENTMEMORY_TOOLS=all` for all)
- 128 REST endpoints
- 54 MCP tools (`all` by default; 7 safe essentials in `core`; curated coordination in `workstation`)
- 131 REST endpoints
- 6 MCP resources, 3 MCP prompts
- 12 hooks, 15 skills
- 50+ iii functions
Expand Down
2 changes: 1 addition & 1 deletion INSTALL_FOR_AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,7 @@ These are off by default because they spend tokens. Enable them only if the user

## Tool surface

The MCP server exposes 53 tools by default (`--tools all`). Use `--tools core` (or `AGENTMEMORY_TOOLS=core`) for a lean 8-tool set on hosts with tight tool limits. The 8 core tools cover save, recall, consolidate, smart search, sessions, diagnose, lesson save, and reflect.
The MCP server exposes 53 tools by default (`--tools all`). Use `--tools core` (or `AGENTMEMORY_TOOLS=core`) for a lean 7-tool set on hosts with tight tool limits. The 7 core tools cover save, recall, smart search, sessions, diagnose, lesson save, and lesson recall. `AGENTMEMORY_TOOLS=workstation` adds actions, leases, and signals without exposing disabled LLM workflows.

## Lifecycle commands

Expand Down
Loading