Skip to content

feat(plugins): Memory Pack — hierarchical persistent memory for AI agents - #33

Merged
rrader26 merged 1 commit into
mainfrom
feat/memory-pack
May 12, 2026
Merged

feat(plugins): Memory Pack — hierarchical persistent memory for AI agents#33
rrader26 merged 1 commit into
mainfrom
feat/memory-pack

Conversation

@rrader26

Copy link
Copy Markdown
Contributor

Summary

  • New `createMemoryPlugin()` adds 5 MCP tools for persistent, hierarchically-scoped agent memory.
  • Designed to fix per-session amnesia for IDE coding assistants (Claude Code / Cursor / Codex / Windsurf).
  • Cross-platform pure-Node. Backed by a single JSON file (mode 0600); atomic temp-file + rename writes.

Tools

Tool Use
`agentmark_memory_set` Store a memory under a scope, with optional tags + TTL
`agentmark_memory_get` Lookup by key; optionally walk a `scopes` array for hierarchical resolution
`agentmark_memory_search` Substring + tag + scope filtering; sort by recency / access_count / created
`agentmark_memory_list` Enumerate within a scope (optional prefix filter)
`agentmark_memory_delete` By `record_id` OR by `key` + `scope`

Scope hierarchy

Five levels, queried most-specific → most-general:

  • platform — global to this install
  • project — scoped to a repo / working directory
  • agent — scoped to one AI agent (e.g. one Claude Code session)
  • user — scoped to an end-user identity
  • session — scoped to one MCP connection

`agentmark_memory_get { key: "editor", scopes: [project, user, platform] }` resolves in one call: project value wins, falls back to user default, falls back to platform default.

Why this PR matters

The IDE coding-assistant category (Claude Code, Cursor, Codex, Windsurf) is bottlenecked by amnesia. Every session relearns "this repo uses pnpm not npm", "build command is X", "the user prefers terse code reviews". A small persistent K/V at the MCP layer makes every assistant smarter, immediately, without per-tool integration work. Aligned with the strategic direction of packaging AgentMark + Memory as a desktop product targeted at developers.

Storage details

  • File: `~/.thinkfleet/agentmark/memory.json` (override via `storePath`)
  • Atomic writes: temp file + `rename()`
  • LRU eviction when total records exceed `maxRecords` (default 10000)
  • TTL per-record; expired records filtered on read
  • Access tracking: `get` + `search` bump `access_count` + `last_accessed_at` (used for both LRU eviction priority and `sort_by="access_count"` search)

Test plan

  • `pnpm build` clean
  • `pnpm test` — 427 pass / 10 skip (22 new tests: store CRUD, scope hierarchy resolution, TTL filtering, LRU eviction, search by substring/tags/scope, dispatcher round-trips)
  • Manual: run from Claude Code; ask it to remember a project convention; reconnect; verify recall

🤖 Generated with Claude Code

…ents

Designed to fix per-session amnesia for IDE coding assistants (Claude
Code, Cursor, Codex, Windsurf). Adds 5 MCP tools the agent uses to
remember things across sessions: project conventions, build commands,
last-known-good states, user preferences.

Tools shipped (5):
  agentmark_memory_set      store a memory under a scope
  agentmark_memory_get      look up by key, optionally walking a scope hierarchy
  agentmark_memory_search   substring + tag search, sortable by recency/usage
  agentmark_memory_list     enumerate within a scope (optional prefix filter)
  agentmark_memory_delete   by record_id OR by key+scope

Five scope levels organise memories so the right granularity surfaces
in the right place:
  - platform: global to this install
  - project:  scoped to a repo / working directory
  - agent:    scoped to one AI agent (e.g. one Claude Code session)
  - user:     scoped to an end-user identity
  - session:  scoped to one MCP connection (lost on disconnect)

`agentmark_memory_get` accepts an ordered `scopes` array — first hit
wins. Use this to resolve "this project's value, falling back to my
user default, falling back to platform default" in one call.

Storage: single JSON file at ~/.thinkfleet/agentmark/memory.json
(mode 0600). Atomic temp-file + rename writes. LRU-evicts when total
records exceed maxRecords (default 10000). TTL support per-record;
expired records filtered on read.

Access tracking: get + search bump access_count + last_accessed_at on
returned records. Used both for LRU eviction priority and for
search sort_by="access_count" (surface the memories the agent
actually uses).

Tests (22 new, 427 total): scope validation, key+scope uniqueness,
hierarchy resolution (project overrides platform), TTL filtering,
LRU eviction with access-recency, substring + tag + scope search,
search scope-type-only filter (no id), delete by record_id and by
key+scope, full dispatcher round-trips.

Aligns with the ThinkFleet Desktop for developer tools direction:
make Claude Code / Cursor / Codex meaningfully more capable by giving
them durable cross-session memory at the MCP layer.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@rrader26
rrader26 force-pushed the feat/memory-pack branch from b7e0ab1 to e22e6b7 Compare May 12, 2026 14:38
@rrader26
rrader26 merged commit 083ae18 into main May 12, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants