e26320e3aa
feat: auto-install iii-engine, clack CLI, viewer lessons tab, README update
...
CLI (src/cli.ts):
- Auto-install iii-engine via curl | sh with interactive clack/prompts
- Edge cases: Windows (manual install note), curl missing, PATH fallback
- Error shows all install methods: curl | sh, cargo install, Docker
- Spinner feedback for install, engine start, readiness check
Viewer (src/viewer/index.html):
- Version v0.5.0 → v0.7.0
- Added Lessons tab with search, confidence gauges, source badges
- Added Lessons + Crystals stat cards to dashboard
- Dashboard fetches lessons and crystals data
README:
- Quick start is now single command: npx @agentmemory/agentmemory
- Prerequisites: iii-engine via curl | sh (not npm)
- Updated all stale counts and version references
AGENTS.md: test count 573 → 581
581 tests passing, all builds clean
2026-04-05 11:28:49 +01:00
ed6f1d64d5
docs: update README for v0.7.0 — npm install, lessons, obsidian, correct counts
...
- Add `npm install -g @agentmemory/agentmemory` as primary install method
- Add npx agentmemory to Quick Start
- Fix stale counts: 38→41 tools, 93→100 endpoints, 573→581 tests,
105→113 source files, 16K→20K LOC, 33→34 KV scopes, 52→57 functions
- Fix version in health example: 0.6.1→0.7.1
- Add v0.7.0 functions to table: lesson-save/recall/list/strengthen/decay-sweep, obsidian-export
- Add mem:lessons to KV scopes table
- Add 5 new REST endpoints to API table
- Add v0.7.0 env vars: LESSON_DECAY_ENABLED, OBSIDIAN_AUTO_EXPORT, AGENTMEMORY_TOOLS
- Update CONSOLIDATION_ENABLED example to true (opt-in)
- Update Node.js requirement to >=20
- Update export format reference to include v0.7.0 + lessons
2026-04-05 01:10:18 +01:00
e8f410b537
feat: v0.7.0 — lessons, tool visibility, auto-consolidation, obsidian export, npx bootstrap ( #82 )
...
* feat: v0.7.0 — lessons, tool visibility, auto-consolidation, obsidian export, npx bootstrap
Five DX improvements based on competitive research against Mem0, Engram, CodeMem:
1. `npx agentmemory` zero-config startup
- New CLI bootstrap (src/cli.ts) auto-detects and starts iii-engine
- Tries `iii` binary first, falls back to `docker compose up -d`
- Bundles iii-config.yaml and docker-compose.yml in dist/
2. Simplified MCP tool surface (7 core tools by default)
- AGENTMEMORY_TOOLS=all unlocks all 49 tools
- Default: save, recall, consolidate, forget, sessions, diagnose, lesson_save
- Call handler remains unfiltered — any tool callable by name
3. Auto-consolidation on session end
- CONSOLIDATION_ENABLED defaults to true (was false)
- Session-end hook: session/end → crystallize → consolidate → bridge sync
- Consolidation pipeline always registered (timer gated by config)
4. First-class lesson memory type with confidence decay
- Lesson interface: confidence (0-1), reinforcements, decayRate, source
- 5 functions: lesson-save, lesson-recall, lesson-list, lesson-strengthen, lesson-decay-sweep
- Dedup via SHA-256 fingerprint — duplicate saves strengthen existing
- Crystal lessons auto-flow into lesson system at confidence 0.6
- Daily decay sweep with parallel KV writes
5. Obsidian-compatible Markdown export
- Export to ~/.agentmemory/vault/ with YAML frontmatter + wikilinks
- MOC.md (Map of Content) index file
- Parallel KV reads, auto-export via OBSIDIAN_AUTO_EXPORT=true
Stats: 49 MCP tools, 99 REST endpoints, 573 tests passing
* docs: add AGENTS.md, fix tool/endpoint counts across README, plugin, cli
- Create AGENTS.md with strict consistency rules for MCP tools, REST
endpoints, versions, KV scopes, and audit operations
- Fix MCP tool count: 38 → 41 across README.md (4 occurrences)
- Fix REST endpoint count: 93/95 → 99 across README.md and index.ts
- Fix plugin.json: version 0.6.1 → 0.7.0, tool count 5 → 41
- Fix cli.ts help text: 48+ → 41 MCP tools
- Fix README api.ts path reference → triggers/api.ts
* fix: address code review findings — consolidation guard, decay bug, async fs, export-import lessons
Inline fixes:
- Revert CONSOLIDATION_ENABLED to opt-in (=== "true"), matching original behavior
- Add early-exit guard in consolidation-pipeline handler when disabled
- Gate session-end crystallize+consolidation calls on CONSOLIDATION_ENABLED
- Fix lesson decay over-decay bug: add lastDecayedAt to Lesson, compute
incremental delta instead of reapplying full age every sweep run
- Add LESSON_DECAY_ENABLED flag (default true) to gate the sweep timer
Outside diff fixes:
- Add lessons to export-import (export + import + replace cleanup)
- Log warning instead of swallowing obsidian auto-export errors
Nitpick fixes:
- Switch obsidian-export to async fs/promises (mkdir, writeFile)
- Add per-item try/catch in obsidian-export, return errors array
- Replace governance_delete with smart_search in ESSENTIAL_TOOLS (non-destructive default)
- Fix CLI whichBinary for Windows (uses "where" on win32)
- Use dynamic port in CLI error message instead of hardcoded 3111
- Return 201 for newly created lessons, 200 for strengthened
- Wrap lesson audit calls in try/catch so audit failure doesn't surface
- Fix build script to not swallow tsdown failure
- Remove exact tool count from test, use >=41 + uniqueness + required names
- Add test/consistency.test.ts: validates version, tool count, README consistency
- Add isConsolidationEnabled mock to consolidation-pipeline test
579 tests passing (573 original + 6 new consistency checks)
* fix: guard remaining audit calls, correct endpoint count, add CI + npm publish
Review fixes:
- Wrap lesson_recall and lesson_strengthen audit calls in try/catch
- Fix REST endpoint count: 99 → 100 (verified via grep) across index.ts,
README.md, and AGENTS.md
- Use regex in consistency test for README assertions (flexible phrasing)
- Add consolidation gate tests: disabled returns early, force=true bypasses
CI/CD:
- Add .github/workflows/ci.yml — test on Node 18/20/22
- Add .github/workflows/publish.yml — auto-publish to npm on GitHub release
(uses NPM_TOKEN secret + provenance)
Nitpick:
- Single-char term filter (t.length > 1) kept intentionally — prevents noise
from single-letter matches; documented in AGENTS.md if needed
581 tests passing
* fix(ci): add --legacy-peer-deps for zod v3/v4 peer conflict
@anthropic-ai/claude-agent-sdk@0.2.56 requires zod@^4.0.0 as a peer
dependency but the project uses zod@^3.23.0. The lock file resolves
this locally but npm ci is strict about peer deps in CI.
* fix(ci): drop Node 18 from matrix — tsdown requires Node 20+
tsdown/rolldown uses node:util.styleText which is only available in
Node 20.12+. Updated engines field to >=20.0.0 to match.
* fix(ci): add inlineOnly: false to tsdown config, target node20
tsdown errors on CI with "Consider adding inlineOnly option" when
dependencies are bundled. Setting inlineOnly: false suppresses this.
Also updated target from node18 to node20 to match engines field.
2026-04-04 17:57:01 +01:00
e5f42c4d01
docs: update README for v0.6.1 — punchy intro, updated stats ( #80 )
...
- Add two-paragraph technical pitch above the fold with 3-line quick start
- Update tool count 37→38 (memory_verify), function count 50→52, test count 573
- Add memory_verify to MCP tools table, mem::verify and mem::cascade-update to functions table
- Add citation provenance and cascading staleness to capabilities table
- Add cross-agent sync and memory trust to comparison table
- Update API endpoint count 93→95, version 0.6.0→0.6.1
2026-03-25 21:21:01 +00:00
857f71e3c6
feat: v0.6.0 advanced retrieval with real-world benchmarks ( #76 )
...
* feat: add 9 orchestration modules for v0.5.0
Add actions, frontier, leases, routines, signals, checkpoints,
flow-compress, mesh, and branch-aware modules with full MCP tools,
REST endpoints, and 170 new tests. Includes SSRF protection,
race-condition-safe keyed mutex locking, SHA-256 fingerprinting,
and fixes for 29 CodeRabbit review findings.
- 9 new source files (src/functions/*)
- 8 new test files (170 tests, total 386)
- 10 new MCP tools, 23 new REST endpoints
- 8 new KV scopes, new types for orchestration
- Version bump to 0.5.0, README and viewer updated
* feat: add sentinels, sketches, crystallize, diagnostics, facets modules
5 new modules inspired by beads patterns but with original naming and
iii-engine real-time streaming (no polling):
- sentinels: event-driven condition watchers (webhook, timer, threshold,
pattern, approval) that auto-unblock gated actions via SSE
- sketches: ephemeral action graphs with auto-expiry, promote or discard
- crystallize: LLM-powered compaction of completed action chains into
compact crystal digests with key outcomes and lessons
- diagnostics: self-diagnosis across 8 categories (actions, leases,
sentinels, sketches, signals, sessions, memories, mesh) with auto-heal
- facets: multi-dimensional tagging (dimension:value) with AND/OR queries
- 5 new source files, 5 new test files (132 tests, total 518)
- 9 new MCP tools (total 37), 21 new REST endpoints (total 93)
- 4 new KV scopes (total 33), new types for all modules
- README stats and function table updated
* fix: address code review findings across v0.5.0 modules
- actions: validate edges before persisting, set blocked status for requires deps
- leases: use mem:action lock key, reject blocked actions, check expiry on release
- checkpoints: validate linkedActionIds exist, check requires edges in unblock
- mesh: add SSRF validation on peer registration
- routines: remove invalid "failed" action status check
- export-import: add v0.5.0 scope export/import (actions, sentinels, sketches, etc)
- mcp/server: validate CSV inputs are strings before splitting
- schema: replace runtime require with static import
- README: fix stale tool/endpoint counts (28→37, 72→93)
* fix: second round code review — mesh locks, routines DAG, MCP input validation, README counts
- mesh.ts: add withKeyedLock on action writes in receive path, add IPv6 private ranges to SSRF check
- routines.ts: validate DAG (duplicate orders, unknown deps), set dep actions to blocked, refresh stepStatus in routine-status
- checkpoints.ts: runtime type enum validation, set linked pending actions to blocked
- leases.ts: validate ttlMs is finite positive number
- export-import.ts: add skip strategy checks for all v0.5.0 import blocks
- mcp/server.ts: typeof guards on tags, config JSON.parse, actionIds, linkedActionIds, categories
- README.md: Tools 18→37, Functions 33→50, stats line updated
- test: update checkpoint test for new blocked-on-create behavior
* fix: third round review — lease renew/release safety, mesh locking, export replace cleanup, MCP input guards
- leases.ts: renew extends from max(now, existing expiry) instead of now; release verifies action ownership before mutation
- mesh.ts: withKeyedLock on memory writes in mesh-receive; applySyncData validates id/updatedAt and locks both memory and action writes
- routines.ts: stepStatus maps "blocked" to "pending" explicitly; progress includes blocked/cancelled counts; routine-freeze wrapped in withKeyedLock
- export-import.ts: remove unused RoutineRun import; replace strategy clears all orchestration namespaces; skip strategy for graphNodes/graphEdges/semantic/procedural
- mcp/server.ts: sentinel_trigger JSON.parse with typeof+try/catch; facet_query typeof guards on matchAll/matchAny; remove redundant requires cast; .filter(Boolean) on concepts/files/tags/requires CSV splits
- README.md: clarify API table is a representative subset
* fix: fourth round review — redirect SSRF, blocked-on-create, missing action handling, boolean normalization
- mesh.ts: add redirect:"error" to both outbound fetch calls to prevent SSRF via redirect
- routines.ts: create actions with status "blocked" directly when hasDeps (eliminates two-pass race); handle missing actions in routine-status as cancelled; progress.total uses run.actionIds.length
- mcp/server.ts: sentinel config accepts object values directly; normalize unreadOnly/dryRun for both JSON booleans and string values
- README.md: consistent bundle size (365KB) across both occurrences
* feat: v0.6.0 advanced retrieval — triple-stream search, stemming, real benchmarks
Search improvements:
- Porter stemmer for word normalization (authentication ↔ authenticating)
- 40+ coding-domain synonym groups (db ↔ database, k8s ↔ kubernetes)
- Binary-search prefix matching replaces O(n) full scan
- Session diversification (max 3 results per session)
- Co-occurrence graph edges between all concept pairs
New retrieval modules:
- Sliding window inference pipeline (context enrichment at ingestion)
- Adaptive query expansion (LLM-generated reformulations)
- Triple-stream search (BM25 + Vector + Graph with RRF fusion)
- Append-only temporal knowledge graph (versioned edges, point-in-time queries)
- Graph-augmented retrieval (entity search + neighborhood expansion)
- Ebbinghaus retention scoring (decay + tiered hot/warm/cold/evictable)
Real-world benchmarks (240 observations, 20 labeled queries):
- Quality eval: 64.1% recall@10 with Xenova embeddings (vs 55.8% grep)
- Scale eval: 92-100% token savings vs built-in memory at 240-50K observations
- Cross-session: 12/12 queries found vs 10/12 for 200-line MEMORY.md cap
- Token measurement uses actual search results (fixed fake constant bug)
- Removed old microbenchmarks (bench.ts, run-bench.ts, COMPARISON.md)
2026-03-18 08:47:35 +00:00
1ca0ec0414
feat: v0.5.0 orchestration layer — 14 modules, 518 tests ( #74 )
...
* feat: add 9 orchestration modules for v0.5.0
Add actions, frontier, leases, routines, signals, checkpoints,
flow-compress, mesh, and branch-aware modules with full MCP tools,
REST endpoints, and 170 new tests. Includes SSRF protection,
race-condition-safe keyed mutex locking, SHA-256 fingerprinting,
and fixes for 29 CodeRabbit review findings.
- 9 new source files (src/functions/*)
- 8 new test files (170 tests, total 386)
- 10 new MCP tools, 23 new REST endpoints
- 8 new KV scopes, new types for orchestration
- Version bump to 0.5.0, README and viewer updated
* feat: add sentinels, sketches, crystallize, diagnostics, facets modules
5 new modules inspired by beads patterns but with original naming and
iii-engine real-time streaming (no polling):
- sentinels: event-driven condition watchers (webhook, timer, threshold,
pattern, approval) that auto-unblock gated actions via SSE
- sketches: ephemeral action graphs with auto-expiry, promote or discard
- crystallize: LLM-powered compaction of completed action chains into
compact crystal digests with key outcomes and lessons
- diagnostics: self-diagnosis across 8 categories (actions, leases,
sentinels, sketches, signals, sessions, memories, mesh) with auto-heal
- facets: multi-dimensional tagging (dimension:value) with AND/OR queries
- 5 new source files, 5 new test files (132 tests, total 518)
- 9 new MCP tools (total 37), 21 new REST endpoints (total 93)
- 4 new KV scopes (total 33), new types for all modules
- README stats and function table updated
* fix: address code review findings across v0.5.0 modules
- actions: validate edges before persisting, set blocked status for requires deps
- leases: use mem:action lock key, reject blocked actions, check expiry on release
- checkpoints: validate linkedActionIds exist, check requires edges in unblock
- mesh: add SSRF validation on peer registration
- routines: remove invalid "failed" action status check
- export-import: add v0.5.0 scope export/import (actions, sentinels, sketches, etc)
- mcp/server: validate CSV inputs are strings before splitting
- schema: replace runtime require with static import
- README: fix stale tool/endpoint counts (28→37, 72→93)
* fix: second round code review — mesh locks, routines DAG, MCP input validation, README counts
- mesh.ts: add withKeyedLock on action writes in receive path, add IPv6 private ranges to SSRF check
- routines.ts: validate DAG (duplicate orders, unknown deps), set dep actions to blocked, refresh stepStatus in routine-status
- checkpoints.ts: runtime type enum validation, set linked pending actions to blocked
- leases.ts: validate ttlMs is finite positive number
- export-import.ts: add skip strategy checks for all v0.5.0 import blocks
- mcp/server.ts: typeof guards on tags, config JSON.parse, actionIds, linkedActionIds, categories
- README.md: Tools 18→37, Functions 33→50, stats line updated
- test: update checkpoint test for new blocked-on-create behavior
* fix: third round review — lease renew/release safety, mesh locking, export replace cleanup, MCP input guards
- leases.ts: renew extends from max(now, existing expiry) instead of now; release verifies action ownership before mutation
- mesh.ts: withKeyedLock on memory writes in mesh-receive; applySyncData validates id/updatedAt and locks both memory and action writes
- routines.ts: stepStatus maps "blocked" to "pending" explicitly; progress includes blocked/cancelled counts; routine-freeze wrapped in withKeyedLock
- export-import.ts: remove unused RoutineRun import; replace strategy clears all orchestration namespaces; skip strategy for graphNodes/graphEdges/semantic/procedural
- mcp/server.ts: sentinel_trigger JSON.parse with typeof+try/catch; facet_query typeof guards on matchAll/matchAny; remove redundant requires cast; .filter(Boolean) on concepts/files/tags/requires CSV splits
- README.md: clarify API table is a representative subset
* fix: fourth round review — redirect SSRF, blocked-on-create, missing action handling, boolean normalization
- mesh.ts: add redirect:"error" to both outbound fetch calls to prevent SSRF via redirect
- routines.ts: create actions with status "blocked" directly when hasDeps (eliminates two-pass race); handle missing actions in routine-status as cancelled; progress.total uses run.actionIds.length
- mcp/server.ts: sentinel config accepts object values directly; normalize unreadOnly/dryRun for both JSON booleans and string values
- README.md: consistent bundle size (365KB) across both occurrences
2026-03-09 09:08:56 +00:00
3ef216ebd6
fix: replace static thumbnail with animated GIF demo ( #73 )
...
Convert mp4 to GIF using ffmpeg two-pass palettegen (720p, 15fps,
Floyd-Steinberg dithering) for inline playback on GitHub README.
Remove unused thumbnail.
2026-03-04 11:27:53 +00:00
3b3db8d22a
fix: use clickable thumbnail for demo video in README ( #72 )
...
GitHub doesn't render <video> tags in markdown. Replace with a
clickable thumbnail image that links to the raw mp4 file.
2026-03-04 11:20:00 +00:00
b9d7ea93c8
docs: add demo video to README ( #71 )
2026-03-04 11:07:01 +00:00
11652fa742
docs: update README with viewer section and accurate stats ( #70 )
...
- Add Real-Time Viewer section with feature list
- Update stats: 87 source files, ~11,300 LOC, 232KB bundled
- Add viewer port info to Quick Start and Configuration
- Add Viewer link to nav bar
2026-03-04 07:38:41 +00:00
134cf96124
feat: agentmemory v0.4.0 — the memory layer for all AI coding agents ( #9 )
...
* feat: agentmemory v0.4.0 — the memory layer for all AI coding agents
7 new features: Claude Code memory bridge, standalone cross-agent MCP server,
knowledge graph with entity extraction, 4-tier memory consolidation pipeline,
team/shared memory, memory governance with audit trail, git-versioned snapshots.
33 functions, 18 MCP tools, 6 MCP resources, 3 MCP prompts, 49 REST endpoints,
21 KV scopes, 216 tests. All features opt-in via env vars.
* fix: address 28 CodeRabbit findings across v0.4.0 codebase
Critical: Fix bin path mismatch (dist/mcp-standalone.mjs -> dist/standalone.mjs)
Bugs: Fix procedural decay, parseFloat||0.5 for zero values, snapshot restore
missing graphNodes/observations, git catch too broad, N+1 graph query, BFS
duplicate edges, array mutation in audit sort, date validation
Improvements: Lazy readline in transport, JSON-RPC validation, persist error
handling, ID collision prevention, defensive null coalescing for concepts/files,
Windows backslash support in config, direction required for bridge sync tool,
try-catch for audit/governance MCP, team profile fallback teamId, POST body for
bridge sync hook, observations validation for graph-extract endpoint, await in test
2026-03-01 18:03:36 +00:00
5c4ef047ca
docs: update README for v0.4.0 ( #8 )
...
* docs: update README for v0.4.0 — MCP resources, prompts, enrichment, confidence
Update stats (173 tests, 22 functions, 29 REST + 4 MCP endpoints, 142KB),
add MCP resources/prompts/endpoints sections, document enrich endpoint,
confidence scoring on relationships, and liveness probe.
* fix: correct REST endpoint count to 34 (28 core + 6 MCP)
Update three locations that incorrectly stated 29 endpoints to reflect
the actual 34 endpoints in the API table. Add http language specifier
to MCP endpoints code block.
2026-03-01 16:38:21 +00:00
d400b051da
docs: rewrite README for v0.3.0 — what, why, and agent support ( #5 )
...
* docs: rewrite README for v0.3.0
- Add "Why agentmemory" section explaining what it provides and comparison table
- Add "Supported Agents" section with native hooks, MCP, and REST API paths
- Add integration decision matrix for choosing the right approach
- Document hybrid search, embedding providers, and progressive disclosure
- Document memory evolution, versioning, relationships, and auto-forget
- Document project profiles, timeline, export/import
- Update all stats (21 functions, 10 MCP tools, 28 endpoints, 144 tests)
- Update data model with new KV scopes (relations, profiles, embeddings, bm25)
- Update config section with embedding, fallback, and search weight env vars
* docs: add banner image to README
* docs: fix banner crop and size
Remove cream strip at bottom, cap width to 720px in README
* docs: include REST API in supported agents intro
Consistent wording in both the intro line and REST section
2026-02-27 11:32:42 +05:30
54deeb33d8
fix: normalize version to 0.2.0 across all files
...
Package.json, telemetry, health endpoint, startup log, and README
all consistently reference v0.2.0 now.
2026-02-27 11:33:48 +05:30
ed07418a71
docs: update README for v0.3.0
...
Reflects all v0.3.0 features: self-evaluation framework, health monitoring,
circuit breaker, BM25 search, dedup, eviction, MCP server (5 tools),
4 skills, 12 hooks, 20 API endpoints, and updated architecture stats.
2026-02-27 11:33:48 +05:30
6df02d3e20
add plugin marketplace install support
...
- Add .claude-plugin/marketplace.json for /plugin marketplace add
- Build hook scripts into plugin/scripts/ (self-contained)
- Fix hooks.json to use ${CLAUDE_PLUGIN_ROOT} paths
- Update README with plugin install as primary quick start
2026-02-27 11:33:48 +05:30
feffc5a362
add integration tests, polish README, simplify code
...
- Add integration test suite covering all 11 API endpoints
- Rewrite README for clarity and user-friendliness
- Extract VIEWER_CSP constant, remove dead IndexEntry.terms field
- Consolidate SIGINT/SIGTERM handlers
2026-02-27 11:33:48 +05:30
37de9e5d02
feat: agentmemory v0.1.0 -- persistent memory for AI coding agents
2026-02-27 11:32:40 +05:30
Rohit Ghumare