Adds a full set of light-background SVG tags in assets/tags/light/
that mirror the existing dark-background tags in assets/tags/.
GitHub <picture> element auto-swaps based on the reader's theme:
- GitHub LIGHT theme → dark-bg SVG (original, stands out on white)
- GitHub DARK theme → light-bg SVG (new, stands out on dark)
## 30 light variants generated
Same dimensions, same orange #FF6B35 brand accent, same fonts. Only
the backgrounds and text colors change:
- Background: white → light gray gradient (#FFFFFF → #F8F9FB)
- Border: #E5E7EB (GitHub-style neutral border)
- Title text: #0F172A (slate-900)
- Subtitle text: #64748B (slate-500)
Stat values are slightly darkened for better contrast on white:
- Green: #00D26A → #16A34A
- Orange: #FF6B35 → #EA580C
- Purple: #B5A4FF → #7C3AED
## README changes
All 26 tag references now use <picture> elements:
<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/foo.svg">
<img src="assets/tags/foo.svg" alt="..." height="..." />
</picture>
Covers: 14 section headers (both stat rows × 6 = 12 stat cards).
No visual changes for light-theme readers — the original dark SVGs
still show. Dark-theme readers now get proper contrast instead of
dark-on-dark blend.
All 30 light SVGs validated with xmllint. 654/654 tests passing.
* feat: flashy README with real agent logos + paste-this-prompt blocks for integrations
## Main README — real logos in Supported Agents grid
Replaced plain text cells with real brand logos for all 16 supported agents:
- simple-icons CDN for: Claude Code (Anthropic), Cursor, Gemini CLI
(Google Gemini), Codex CLI (OpenAI), Windsurf, Claude Desktop, Claude SDK
- GitHub org avatars for: OpenClaw, OpenCode (opencode-ai), Cline,
Hermes (NousResearch), Goose (block), Kilo Code (kilo-org), Aider
(Aider-AI), Roo Code (RooCodeInc)
- Shield badge for the generic "Any agent" cell
Each logo is clickable and links to the upstream project. The OpenClaw and
Hermes cells now link directly to integrations/openclaw and integrations/hermes
so users can find the deeper plugin integration.
Added tagline footer below the grid reinforcing the cross-agent story.
## Integration READMEs — paste-this-prompt blocks
Following the gstack pattern, both integration READMEs now open with a
visual hero (upstream logo + agentmemory logo) and a copy-pasteable text
block the user can drop into their agent. The agent handles the entire
setup — start server, update MCP config, verify health, open viewer.
This matches the "paste this into Claude Code" block we already have in
the main README for Claude Code users.
### openclaw/README.md
- Centered hero: OpenClaw org avatar + agentmemory icon
- Shield badges: 43 MCP tools, 4 lifecycle hooks, 95.2% R@5, self-hosted
- "Install it in 30 seconds" section with the paste-this prompt
### hermes/README.md
- Centered hero: NousResearch avatar + agentmemory icon
- Shield badges: 43 MCP tools, 6 lifecycle hooks, 95.2% R@5, self-hosted
- "Install it in 30 seconds" section with the paste-this prompt
All 654 tests still passing.
* fix: reorder agents, replace broken logos, add OpenClaw/Hermes paste blocks, cleaner hero
## Main README
### Supported Agents grid — 3 fixes
1. **Reorder**: OpenClaw and Hermes now in positions 2 and 3 (right after
Claude Code), since they have first-class gateway plugins in
integrations/. Users shouldn't have to scroll to find them.
2. **Fix broken Codex logo**: simple-icons CDN returned 404 for the
OpenAI slug with black color. Switched ALL logos to GitHub org
avatars (github.com/<org>.png?size=120) which are bulletproof and
always return real images. Verified 7/7 resolve to actual PNGs.
3. **Bigger logos**: bumped from 40px to 48px for more visual weight.
### Paste-this-prompt toggles
Added two collapsible <details> blocks after the Claude Code paste
prompt: one for OpenClaw, one for Hermes. Each contains a complete
copy-pasteable setup prompt that the agent can execute, plus a link
to the full integration guide.
## Integration README heroes — redesigned
The old hero had two logos separated by an ugly gray "+" shield badge
that looked cheap. Replaced with:
- agentmemory banner.png as the centered hero image
- H1 title with a small inline upstream logo (28px) next to the title
- Bolded tagline + subtitle with upstream link
- Shield badge row (MCP tools, hooks, R@5, self-hosted, license)
Much cleaner and follows the main README's visual pattern.
Verified: 654/654 tests passing.
* Update README.md
* feat: custom SVG tags for section headers (no emojis)
Replaces emoji section headers with custom SVG badges matching the
agentmemory brand style (orange #FF6B35 accent on dark #1A1A1A).
Inspired by shanraisshan/claude-code-best-practice's custom tag
approach in its !/ directory.
## Custom SVG tags created (30 total in assets/tags/)
### 14 section headers (section-*.svg)
Each is a 44px-tall dark rounded badge with:
- Orange gradient accent strip on the left (brand color #FF6B35 → #FF8F5E)
- Uppercase title in white, 800 weight, 2.2 letter-spacing
- Light gray subtitle (#9CA3AF) with section context
- Subtle #2A2A2A border on dark #1A1A1A → #0F0F0F gradient
Sections: works-with-every-agent, benchmarks, vs-competitors, quick-start,
why, how-it-works, search, mcp-server, real-time-viewer, configuration,
api, architecture, development, license.
### 6 hero stat blocks (stat-*.svg)
Big numbers with small uppercase labels, replacing the shield.io badge
row in two places (hero + benchmarks section):
- stat-recall: 95.2% R@5 (green)
- stat-tokens: 92% fewer tokens (green)
- stat-tools: 43 MCP tools (orange)
- stat-hooks: 12 auto hooks (orange)
- stat-deps: 0 external DBs (purple)
- stat-tests: 654 tests passing (green)
### 8 pill tags (pill-*.svg)
Rounded pills with colored dot indicator for inline status tags:
MCP, AUTO HOOK, SKILL, NEW, BETA, STABLE, PLUGIN, SECURE.
### 1 "New in v0.8.2" version tag
Dark pill with orange v0.8.2 version marker.
### 1 section divider
Horizontal line with orange diamond in the middle (unused for now,
available for future sections).
## README changes
- All <h2> section headers now use <img> tags pointing to the SVG
- Hero stats row replaced with stat-*.svg row (same visual position)
- Benchmarks stats row replaced with the same stat-*.svg row
- Nav links updated to match the new h2 anchor IDs
- "New in v0.8.2" callout uses new-v082.svg tag + note
- Cursor grid cell fixed (was missing <strong>Cursor</strong> label)
- Zero emojis in the entire README
All 30 SVGs validated with xmllint, 654/654 tests passing.
* Remove version 0.8.2 image from README
Removed image tag for version 0.8.2 from README.
* feat: add demo command, benchmark comparison, OpenClaw integration, token cost in viewer
Product & ecosystem improvements surfaced from the last30days research
and competitive analysis of the AI agent memory space.
## New
### agentmemory demo command
Seeds 3 realistic sessions (JWT auth, N+1 query fix, rate limiting)
and runs smart-search queries against them. Shows token-aware semantic
search finding "N+1 query fix" when you search "database performance
optimization" — proof that keyword matching can't do that.
npx @agentmemory/agentmemory demo
Surfaces the "show don't tell" moment in 30 seconds without requiring
the user to integrate anything.
### benchmark/COMPARISON.md
Head-to-head comparison vs mem0 (53K stars, 68.5% LoCoMo),
Letta/MemGPT (22K stars, 83.2% LoCoMo), Khoj (34K stars),
claude-mem (46K stars), and Hippo. Feature matrix across 18
dimensions. Token efficiency table. Honest caveats about LongMemEval
vs LoCoMo apples-vs-oranges. Lets users compare without trusting our
README.
### integrations/openclaw/
OpenClaw gateway plugin following the same pattern as the Hermes
integration. README, plugin.yaml with hooks config, and plugin.mjs
implementing the 4 lifecycle hooks (on_session_start, on_pre_llm_call,
on_post_tool_use, on_session_end). Gets agentmemory into the OpenClaw
ecosystem for distribution.
## Improved
### Viewer token savings card
Now shows tokens saved AND dollar cost saved (using $0.30/1K as a
reasonable mid-tier model rate) instead of just raw numbers. Makes
the ROI immediately tangible.
### README additions
- "Try it in 30 seconds" section featuring the new demo command
- Competitor comparison link in benchmarks section
- OpenClaw integration link in supported agents table
* refactor: simplify demo command and OpenClaw plugin
- Extract postJson helper in cli.ts runDemo (4x repeated fetch boilerplate → single call site)
- Break runDemo into buildDemoSessions, seedDemoSession, runDemoSearch for single-responsibility
- Replace three-branch if/else command dispatch with a commands map (single error handler)
- Extract typed DemoSession/DemoObservation/SearchResult interfaces
- Simplify OpenClaw plugin.mjs: collapse headers() + fetchJson() into a single postJson method
Each hook is now ~5 lines instead of ~10
No behavior change. 654/654 tests passing, CLI help and error paths verified.
* fix: address CodeRabbit review on growth changes
## plugin.mjs
- Honor the enabled config flag: constructor now sets this.enabled and
all four hooks (onSessionStart, onPreLlmCall, onPostToolUse,
onSessionEnd) return early when disabled
- Fail-fast on non-OK HTTP: previously !res.ok returned null regardless
of fallbackOnError. Now throws with status/statusText/body when
fallbackOnError is false
- Update header JSDoc to use the real hook names instead of the
fictional prefetch/capture/consolidate
## openclaw README.md
- Replace stale hook names (prefetch/capture/consolidate) with the
actual onSessionStart/onPreLlmCall/onPostToolUse/onSessionEnd names
matching plugin.mjs
- Add 'text' language identifier to the Project profile code fence to
satisfy markdownlint MD040
## cli.ts
- Replace ad-hoc Date.now()-based session IDs with generateId("demo")
from src/state/schema.ts, matching the rest of the codebase
(snapshot.ts, migrate.ts, consolidation-pipeline.ts)
- Add postJsonStrict helper that throws on non-OK with status + body
- seedDemoSession now uses postJsonStrict for session/start and
session/end (critical lifecycle calls that should fail fast)
- The observation POST in the loop now inlines the fetch to surface
HTTP errors via p.log.warn with status/body, still only incrementing
the stored counter on success
## viewer/index.html
- Fix token-to-dollar conversion that was 100x underreporting:
tokensSaved / 1000 * 0.3 returns DOLLARS, not cents. Now computes
dollars first, then cents = Math.round(dollars * 100)
- 100K tokens saved now correctly displays $30.00, not 30ct
All 654 tests still passing.
* fix: address 2 more CodeRabbit findings on plugin.mjs
- Use nullish coalescing (??) for config defaults so valid falsy
values like min_confidence: 0 or timeout_ms: 0 aren't overwritten
by defaults. || would clobber them.
- Fix /agentmemory/context payload to match the server contract at
src/triggers/api.ts:115. The handler expects { sessionId, project,
budget? } but the plugin was sending { sessionId, query, tokenBudget,
minConfidence }. Three issues:
1. Missing required 'project' field
2. Wrong field name: 'tokenBudget' should be 'budget'
3. 'query' and 'minConfidence' are not part of this endpoint's
contract (probably belong on /smart-search instead)
Fixes 6 security issues in agentmemory's default deployment, viewer, mesh sync, export path, and startup flow.
## Findings Addressed
1. **Default REST/stream exposure on 0.0.0.0** — bind default REST and stream services to 127.0.0.1; restrict Docker port publishing to localhost; add dedicated iii-config.docker.yaml for Docker usage.
2. **Stored XSS via inline viewer handlers** — remove inline event handlers from the viewer; replace with delegated data-action event handling; switch to nonce-based CSP for viewer HTML; add script-src-attr 'none'.
3. **Arbitrary path writes in Obsidian export** — confine exports to AGENTMEMORY_EXPORT_ROOT (default ~/.agentmemory); reject vaultDir values outside the allowed root.
4. **Mesh sync without peer auth** — require AGENTMEMORY_SECRET for mesh endpoints and sync operations; send Authorization: Bearer <secret> on mesh push/pull requests.
5. **Secret redaction misses modern token formats** — add coverage for Bearer tokens, sk-proj-*, broader sk/pk/rk/ak variants, GitHub ghs_/ghu_ tokens.
6. **CLI executes remote shell script directly** — remove curl|sh installation pattern; use existing local iii-engine binary if available, otherwise fall back to Docker.
## Validation
- 654 tests passing (8 new security tests)
- npm run build succeeds
- Merged with main and resolved README conflicts to preserve the new benchmark/competitor table layout
Thanks @eng-pf for catching these and submitting the fixes.
Replace numbered steps with a single copy-pasteable instruction block
for Claude Code. The agent reads it and handles: engine startup, plugin
install, hook registration, and verification.
Other agents consolidated into a clean table (Cursor, Gemini CLI,
OpenCode, Claude Desktop, SkillKit, REST API) with inline config.
- README: add `text` language tag to fenced code blocks (MD040)
- cli.ts: sessions endpoint returns {sessions: [...]}, not a raw array
- viewer: token budget from URL param instead of hardcoded 2000
- viewer: applyTheme takes persist param, auto-detection doesn't save to
localStorage (prevents OS preference from being overridden on first load)
- logo.svg: full logo mark with memory tiers + retrieval spark
- icon.svg: compact 64x64 app icon variant
- banner.svg: README banner with tagline, stats, supported agents
- README: switch from banner.png to banner.svg
Design: 4 memory tiers (cold→hot) with orange accent (#FF6B35),
retrieval lines converging to a spark node, fading dots for decay.
Rewrite README opening to focus on what the user gets ("your agent
remembers everything, no more re-explaining") instead of internal
architecture ("triple-stream retrieval, 4-tier consolidation").
- Update zod from ^3.23.0 to ^4.0.0 (claude-agent-sdk peer dep conflict)
- Mount iii-config.yaml in docker-compose.yml (missing /app/config.yaml)
- Change host binding from 127.0.0.1 to 0.0.0.0 for Docker compatibility
- Switch npm start from index.mjs to cli.mjs (auto-starts iii-engine)
- Fix CLI health check to detect engine via any HTTP response, not just worker route
- Handle EADDRINUSE on viewer port gracefully instead of crashing
- Fix README step numbering and version in health example
- 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
- 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
* 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
* 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
- 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
Rohit Ghumare