skills/rohitg00__agentmemory
1
0
Fork 0
mirror of https://github.com/rohitg00/agentmemory.git synced 2026-09-14 20:16:33 +08:00
Code Issues Packages Projects Releases Wiki Activity
121 Commits 25 Branches 51 Tags
v0.8.7
Commit Graph

6 Commits

Author SHA1 Message Date
Rohit Ghumare 416fa15af4 chore: release 0.8.6 — scope the MCP shim as @agentmemory/mcp (#134) 
0.8.5's publish workflow got blocked on the unscoped `agentmemory-mcp`
name by npm's name-similarity policy (there's an unrelated third-party
package called `agent-memory-mcp`). Publishing the shim under the
`@agentmemory` scope we already own sidesteps the conflict.

Changes:
- Rename packages/agentmemory-mcp → packages/mcp
- Package name: agentmemory-mcp → @agentmemory/mcp (0.8.4 → 0.8.6)
- Keep bin name `agentmemory-mcp` so `npm i -g @agentmemory/mcp`
  still installs a binary at `agentmemory-mcp` for muscle memory
- Log prefix [agentmemory-mcp] → [@agentmemory/mcp] in standalone.ts
  and in-memory-kv.ts
- README / integrations/openclaw / integrations/hermes / src/cli.ts
  all point at `npx -y @agentmemory/mcp`
- .github/workflows/publish.yml working-directory and npm view queries
  target packages/mcp and @agentmemory/mcp
- Shim dependency on @agentmemory/agentmemory bumped to ~0.8.6
- Main package 0.8.5 → 0.8.6 across the 8 version files
- CHANGELOG [0.8.6] entry documenting the scope move
 2026-04-14 00:31:10 +01:00
Rohit Ghumare 8a36fe7867 fix: retention scoring (#119) + npx agentmemory-mcp 404 (#120), release 0.8.3 (#123) 
* fix: retention scoring (#119) + npx agentmemory-mcp 404 (#120), release 0.8.3

Issue #119 — retention score ignored agent-side reads

`mem::retention-score` previously hardcoded `accessCount=0` and
`accessTimestamps=[]` for episodic memories and used only a single-sample
`lastAccessedAt` for semantic memories, so the time-frequency decay
formula was a dead path. All read endpoints now record access events to
a new `mem:access` KV namespace via a keyed-mutex'd access tracker:

  - mem::search, mem::smart-search (compact + expand), mem::context,
    mem::timeline, mem::file-context, mem::get-related, mem::working-context
  - retention.ts pre-fetches the full access log in one kv.list call,
    normalizes every row defensively, and builds an O(1) lookup Map
  - recordAccessBatch uses Promise.allSettled so a slow keyed-lock on one
    id does not block the rest of the batch
  - Bounded ring buffer of the last 20 access timestamps per memory
  - Backwards-compat fallback: pre-0.8.3 semantic memories with only the
    legacy sem.lastAccessedAt still score correctly
  - Corrupt lastAccessedAt values are NaN-safe via Date.parse + isFinite
  - reinforcementBoost is reported as the raw formula output, not the
    clamped residual

Memory deletion sites (retention-evict, evict, auto-forget,
governance-delete, governance-bulk, forget, import replace) now call
deleteAccessLog to prevent mem:access from accumulating zombie entries.
mem::export / mem::import and mem::snapshot-create / mem::snapshot-restore
round-trip the new namespace so backup/restore cycles no longer zero out
reinforcement signals.

Issue #120 — npx agentmemory-mcp returned npm registry 404

The README instructed users to run `npx agentmemory-mcp`, but
`agentmemory-mcp` only existed as a `bin` entry inside
`@agentmemory/agentmemory`, not a real registry package. Two-part fix:

  - New sibling package `packages/agentmemory-mcp/` — a thin shim that
    depends on `@agentmemory/agentmemory` (~0.8.3, tilde to block 0.9.x
    supply-chain drift) and forwards to dist/standalone.mjs via the new
    `exports` field on the main package
  - Canonical `npx @agentmemory/agentmemory mcp` subcommand on the CLI
    for users who already have the main package installed
  - Removed the dead `agentmemory-mcp` bin from the main package so the
    shim owns the name unambiguously
  - publish.yml publishes both packages in order with idempotent
    guards and npm-view registry polling (no more fixed sleep)
  - All MCP install snippets in README + integrations/openclaw + hermes
    + shim README use `npx -y agentmemory-mcp` to skip install prompts

Release 0.8.3

  - 670 tests passing (665 + 11 new: access tracker, retention,
    smart-search integration, corrupt-input, kv.list failure path,
    Promise.allSettled resilience)
  - Version bumped across package.json, src/version.ts, types.ts,
    export-import supportedVersions, plugin.json
  - package-lock.json regenerated

* fix: address CodeRabbit review feedback on #123

Real issues caught and fixed:

- access-tracker: deleteAccessLog now takes the same mem:access:<id>
  keyed mutex used by recordAccess, eliminating the race where a
  concurrent delete could drop an in-flight RMW update and leave a
  stale access log for an evicted memory
- access-tracker: normalizeAccessLog now coerces count to a
  non-negative integer, drops non-finite recent[] entries, truncates
  recent[] to the last 20 on read (enforcing the ring-buffer invariant),
  and guarantees count >= recent.length so a malformed row can't produce
  NaN downstream. count is NOT capped at 20 — it is the lifetime access
  counter, while recent[] is the 20-entry window
- export-import: import path now rejects accessLogs arrays above
  MAX_ACCESS_LOGS (50_000), normalizes each entry via
  normalizeAccessLog, and drops entries whose memoryId is not in the
  imported memories set, so a crafted export can't blow up memory or
  resurrect zombie access rows for memories that don't exist
- publish.yml: added a post-publish npm view polling loop for
  agentmemory-mcp mirroring the one that already guards the main
  package, so the workflow only succeeds when `npx agentmemory-mcp` is
  actually visible on the registry
- CHANGELOG.md: added the missing [0.8.3] reference-style link target
  at the bottom to match the [0.8.2]/[0.8.1]/[0.8.0] pattern
- README.md: standalone MCP inline examples now use `npx -y` to match
  the MCP config snippets and skip the install confirmation prompt

Tests: 680/680 (+10 new — deleteAccessLog behavior, normalizeAccessLog
invariants, malformed mem:access row handling in retention scoring).

Findings deliberately not applied:

- auto-forget.ts / remember.ts / evict.ts recordAudit calls: existing
  pattern in the codebase only audits governance deletes (user-initiated
  admin actions), not automatic eviction. Adding audit everywhere is a
  policy change, out of scope for this PR
- evict.ts gating deleteAccessLog on memory delete success: current
  order is defensible, deleteAccessLog is already best-effort with its
  own try/catch, and calling it after a failed memory delete is harmless
- snapshot.ts fail-fast on kv.list failure: inconsistent with the
  existing .catch(() => []) pattern used for observations in the same
  function
- retention.ts semantic evict only deletes KV.memories rows: real bug
  but pre-existing on main (RetentionScore has no source/type field).
  Tracked separately — out of scope for this PR
- bin.mjs fallback command: already present in the existing catch
  handler
- Promise.all parallelization of delete+deleteAccessLog: micro
  optimization not worth the readability cost
 2026-04-13 12:05:18 +01:00
Rohit Ghumare 79a7a8ec04 feat: real agent logos + paste-this-prompt blocks for integrations (#114) 
* 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.
 2026-04-12 11:46:45 +01:00
Rohit Ghumare ae8f061cd6 feat: demo command, benchmark comparison, OpenClaw integration (#113) 
* 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)
 2026-04-12 11:05:21 +01:00
Rohit Ghumare 9173b090f4 fix: address review findings on Hermes plugin 
- SSRF prevention: validate URL scheme (http/https only) before urlopen
- on_pre_compress: inject fetched context into messages list (was no-op)
- Remove unused self._secret; _api reads from env directly
 2026-04-09 13:43:34 +01:00
Rohit Ghumare 112e6f4bc0 feat: add Hermes Agent memory provider plugin 
Two integration paths:
1. MCP server (zero code) - add to ~/.hermes/config.yaml
2. Memory provider plugin (deeper) - hooks into Hermes agent loop

Plugin implements the full MemoryProvider ABC:
- prefetch() injects relevant memories before each LLM call
- sync_turn() captures conversation turns in background (non-blocking)
- on_session_end() marks sessions for summarization
- on_pre_compress() re-injects context before compaction
- on_memory_write() mirrors MEMORY.md writes
- system_prompt_block() injects project profile
- 3 tools: memory_recall, memory_save, memory_search

Uses only stdlib (urllib, json, threading). No new dependencies.
 2026-04-09 13:33:10 +01:00