Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
63 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
16e557f
Merge pull request #13 from wrightpt/agent/retire-gh-push-triggers
wrightpt Jul 28, 2026
f8288ce
feat: add curated workstation LLM tool profile
wrightpt Jul 29, 2026
d1f8519
Merge pull request #14 from wrightpt/feat/workstation-llm-tools
wrightpt Jul 29, 2026
d586966
fix: normalize sentence punctuation in URL checks
wrightpt Jul 29, 2026
b1db2f8
Merge pull request #15 from wrightpt/fix/compress-url-validation
wrightpt Jul 29, 2026
23cd3c1
feat: complete workstation LLM MCP surface
wrightpt Jul 29, 2026
a0d11c7
Merge pull request #16 from wrightpt/agent/deepseek-mcp-surface
wrightpt Jul 29, 2026
e59fe65
feat(actions): add bounded graph snapshot reads
wrightpt Jul 29, 2026
532689d
fix(lessons): accept omitted sort order
wrightpt Jul 30, 2026
cf04eaa
feat(lessons): add audited correction API (#17)
wrightpt Aug 2, 2026
495b051
feat(lessons): add causal schema foundation
wrightpt Aug 3, 2026
36806e7
fix: harden causal lesson schema invariants
wrightpt Aug 3, 2026
6af92b3
fix: fail closed on unavailable lesson evidence
wrightpt Aug 3, 2026
3602a45
fix(viewer): render structured lesson facets
wrightpt Aug 3, 2026
867e1ba
Merge pull request #18 from wrightpt/agent/causal-lesson-schema-v1
wrightpt Aug 3, 2026
dfe1aa1
feat: enforce causal lesson access policy
wrightpt Aug 3, 2026
223b2bf
fix: fail closed on lesson access edge cases
wrightpt Aug 3, 2026
7f7437d
fix: close causal lesson access boundaries
wrightpt Aug 3, 2026
ce10a9e
fix: harden remaining lesson access boundaries
wrightpt Aug 3, 2026
c363c61
Merge pull request #19 from wrightpt/agent/causal-lesson-access-v2
wrightpt Aug 3, 2026
af9c58f
feat: add authorized causal lesson hybrid retrieval
wrightpt Aug 3, 2026
9280f46
Merge pull request #20 from wrightpt/agent/causal-lesson-hybrid-retri…
wrightpt Aug 3, 2026
6c27da2
fix(memories): clear dangling supersedes/parentId/relatedIds on delet…
Aug 5, 2026
54f9582
fix(diagnostics): review corrections — gate honesty + concurrency safety
Aug 5, 2026
5568448
Merge pull request #21 from wrightpt/agent/dangling-supersedes-cleanup
wrightpt Aug 5, 2026
abfc83e
fix(lessons): allow implicit worktree scope for legacy prose saves
Aug 5, 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"
]
}
26 changes: 25 additions & 1 deletion .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,24 @@

# AGENTMEMORY_SECRET=your-secret-here

# Structured-lesson authorization is classify-only by default for compatibility.
# To enforce durable-scope and sensitivity access, configure a server-side
# caller policy and give each client a unique high-entropy raw token. The policy
# stores only SHA-256 token digests; never commit raw client tokens.
# AGENTMEMORY_LESSON_ACCESS_MODE=enforce
# AGENTMEMORY_LESSON_CALLER_POLICY_FILE=/etc/agentmemory/lesson-callers.json
# AGENT_ID=codex
# AGENTMEMORY_CALLER_TOKEN=unique-client-token
# Remote lesson embeddings are off by default because query and eligible lesson
# text leave the process. Local embedding providers do not require this opt-in.
# AGENTMEMORY_LESSON_REMOTE_EMBEDDINGS=true
# AGENTMEMORY_LESSON_EMBED_MAX_SENSITIVITY=public # public|internal|confidential|restricted
# AGENTMEMORY_REQUIRE_HTTPS=1 # Refuse credentials over non-loopback plaintext HTTP
# Give the viewer its own server-side read principal. These values are added
# only by the viewer proxy and are never delivered to browser JavaScript.
# AGENTMEMORY_VIEWER_AGENT_ID=viewer-service
# AGENTMEMORY_VIEWER_CALLER_TOKEN=unique-viewer-token

# -----------------------------------------------------------------------------
# 4. Search tuning
# -----------------------------------------------------------------------------
Expand All @@ -106,6 +124,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 @@ -119,14 +138,19 @@
# 6. CLI / runtime knobs
# -----------------------------------------------------------------------------

# AGENTMEMORY_TOOLS=all # core (7 tools, default) | all (51 tools) — surface exposed to MCP clients
# AGENTMEMORY_TOOLS=all # core | workstation | workstation-llm (curated + 7 LLM tools) | all
# AGENTMEMORY_SLOTS=memory # Comma-separated plugin slot names the CLI should claim
# AGENTMEMORY_DEBUG=1 # Trace MCP shim probe + standalone fallback decisions to stderr
# AGENTMEMORY_FORCE_PROXY=1 # Skip the MCP shim livez probe and trust AGENTMEMORY_URL (for sandboxed MCP clients that can't reach localhost)
# AGENTMEMORY_PROBE_TIMEOUT_MS=2000 # MCP shim livez probe timeout
# 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
31 changes: 25 additions & 6 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,22 @@
agentmemory is a persistent memory system for AI coding agents, built on iii-engine's three primitives (Worker/Function/Trigger). Everything goes through `registerFunction`/`registerTrigger`/`sdk.trigger()` — never bypass iii-engine with standalone SQLite or in-process alternatives.

- **Engine**: iii-sdk (WebSocket to iii-engine on port 49134)
- **State**: File-based SQLite via iii-engine's StateModule (`./data/state_store.db`)
- **State**: File-based KV via iii-engine's StateModule (`./data/state_store.db`
is a directory with one file per scope, not a SQLite database)
- **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 +67,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 +112,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 +133,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
- 60 MCP tools (`all` by default; 7 safe essentials in `core`; curated coordination in `workstation`)
- 136 REST endpoints
- 6 MCP resources, 3 MCP prompts
- 12 hooks, 15 skills
- 50+ iii functions
Expand Down
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),

## [Unreleased]

### Added

- **Workstation LLM MCP completion.** Added `memory_enrich_session`, `memory_diagnostic_followup`, and `memory_flow_compress` so the existing engine functions are reachable from MCP clients. Added `memory_llm_smoke`, a fixed-input connectivity probe that reports configured provider/model evidence without persistent AgentMemory or filesystem writes. The `workstation-llm` profile now contains the curated workstation surface plus seven LLM-backed tools.
- **Safe LLM identity metadata.** `/agentmemory/health` now reports `llmConfiguredProvider` and `llmModel` without exposing base URLs or credentials. New `POST /agentmemory/llm/smoke` and `POST /agentmemory/enrich-session` REST endpoints mirror the new MCP operations.

### Changed

- **Surface counts:** 54 → 58 MCP tools and 131 → 133 REST endpoints.

## [0.9.27] — 2026-06-07

Wave release closing several breaking regressions reported against v0.9.26, plus an agent-scope isolation security fix, an iii version-pin audit fix, and a benchmark scorecard correction. No breaking changes; drop-in upgrade.
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