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.
Build script now copies src/viewer/index.html to dist/viewer/.
Also added more candidate paths for index.html resolution so
the viewer works from dist/ (npx), src/ (tsx dev), and repo root.
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)
Address CodeRabbit nitpick on #105: split the result-building loop into
two phases. First filter sequentially (benefits from the per-call
session cache), then batch the kv.get(observations) calls through
Promise.all instead of awaiting them one at a time.
Address CodeRabbit review on #105:
- mem::search now validates query (non-empty string), limit
(positive integer, capped at MAX_LIMIT=100), project and cwd
(must be strings if provided). Throws on invalid input instead
of silently coercing.
- Renamed local 'limit' to 'effectiveLimit' to avoid shadowing.
- ctx.logger no longer emits raw cwd/project (host paths) — logs
only hasProjectFilter/hasCwdFilter booleans.
- api::search whitelists request body fields, returns 400 on
malformed input, and constructs an explicit payload for
sdk.trigger instead of forwarding req.body.
Closes#104
The /agentmemory/search HTTP endpoint and the underlying mem::search
function previously accepted only { query, limit }, returning hits
across all projects on the host. Sessions are already created with
{ project, cwd } via session::start, so this just exposes that scope
on search.
- mem::search now accepts optional project and cwd. When set, results
are filtered by looking up each hit's owning Session.
- To keep the post-filter from starving the result set, the index
fetch is over-fetched (max(limit*10, 100)) when filtering, then
trimmed to limit after filter.
- Session lookups are cached per call.
- api::search forwards the new params; fully backward compatible.
- Add `MinimaxProvider` (`src/providers/minimax.ts`) that calls MiniMax's
Anthropic-compatible API via raw `fetch` instead of the Anthropic SDK.
The SDK auto-injects `x-stainless-*` headers that MiniMax rejects with 403;
using `fetch` directly avoids this entirely.
- Fix `AnthropicProvider` constructor to accept an optional `baseURL` and
forward it to `new Anthropic({ apiKey, baseURL })`. Previously the provider
always connected to `api.anthropic.com` even when `ANTHROPIC_BASE_URL` was
set in `.env`, because `getMergedEnv()` returns a plain JS object that the
Anthropic SDK never sees.
- `detectProvider()` in `config.ts`:
- Checks `MINIMAX_API_KEY` first and returns `provider: "minimax"`.
- Propagates `ANTHROPIC_BASE_URL` as `baseURL` in the Anthropic config.
- Update `ProviderConfig` in `types.ts` to include optional `baseURL` field.
- Update `ProviderType` union to include `"minimax"`.
- Update `VALID_PROVIDERS` set in `config.ts` to include `"minimax"`.
- 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").
Run agentmemory on LongMemEval-S (ICLR 2025, 500 questions) using the
same dataset and metric (recall_any@5) as MemPalace for direct comparison.
Results:
- BM25+Vector hybrid: 95.2% R@5, 98.6% R@10, 87.9% NDCG@10
- BM25-only: 86.2% R@5, 94.6% R@10, 73.0% NDCG@10
- MemPalace raw vector: 96.6% R@5 (1.4pp gap, same embedding model)
Clearly labels these as retrieval recall, not end-to-end QA accuracy.
- author: change from string to object {name, url}
- hooks: remove field (auto-loaded by convention from hooks/hooks.json)
- skills: change from directory string to explicit file path array
- 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
Rohit Ghumare