@xultrax-web/agent-memory-mcp 0.13.1 → 0.13.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +79 -48
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -18,11 +18,11 @@ The wedge:
|
|
|
18
18
|
|
|
19
19
|
---
|
|
20
20
|
|
|
21
|
-
##
|
|
21
|
+
## Memory as constraint · the v0.11 → v0.13 arc
|
|
22
22
|
|
|
23
|
-
|
|
23
|
+
What v0.10 and below shipped: a great file-based memory store. What v0.11+ added: rules that _enforce themselves_. A `rule` memory type carries `severity` (hard / soft), `scope`, `applies_when`, `matches` regex patterns, `enforce_on` categories, and `last_verified` date. From those, the server projects companion files out to every AI tool and gates destructive operations via cryptographic receipts.
|
|
24
24
|
|
|
25
|
-
|
|
25
|
+
### 1. Rule memories project to every tool
|
|
26
26
|
|
|
27
27
|
```bash
|
|
28
28
|
agent-memory save-rule no-emojis-ever \
|
|
@@ -34,11 +34,8 @@ agent-memory save-rule no-emojis-ever \
|
|
|
34
34
|
|
|
35
35
|
agent-memory emit-companions
|
|
36
36
|
# writes AGENTS.md + CLAUDE.md + .cursor/rules/*.mdc + .gemini/instructions.md
|
|
37
|
-
# (v0.11.1 — all four targets · use --target agents,claude to filter)
|
|
38
37
|
```
|
|
39
38
|
|
|
40
|
-
Companion file targets (v0.11.1):
|
|
41
|
-
|
|
42
39
|
| Target | Path | Auto-loaded by |
|
|
43
40
|
| -------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
|
|
44
41
|
| `agents` | `AGENTS.md` | Claude Code, Codex CLI, Cursor, Aider, Devin, Copilot, Gemini CLI, Windsurf, Amazon Q |
|
|
@@ -46,9 +43,9 @@ Companion file targets (v0.11.1):
|
|
|
46
43
|
| `cursor` | `.cursor/rules/operator-hard.mdc` (`alwaysApply: true`) + `operator-conventions.mdc` (agent-requested) | Cursor (MDC format) |
|
|
47
44
|
| `gemini` | `.gemini/instructions.md` | Gemini CLI |
|
|
48
45
|
|
|
49
|
-
Set `AGENT_MEMORY_AUTO_EMIT_DIR=/path/to/project`
|
|
46
|
+
Set `AGENT_MEMORY_AUTO_EMIT_DIR=/path/to/project` and the server re-emits all four files automatically on every rule save.
|
|
50
47
|
|
|
51
|
-
### `check_action` · the protocol enforcement point
|
|
48
|
+
### 2. `check_action` · the protocol enforcement point
|
|
52
49
|
|
|
53
50
|
```bash
|
|
54
51
|
# Agent proposes an action · server matches against rule store
|
|
@@ -71,20 +68,17 @@ MCP shape:
|
|
|
71
68
|
}
|
|
72
69
|
```
|
|
73
70
|
|
|
74
|
-
Tier 1 (deterministic, every client): action
|
|
75
|
-
|
|
76
|
-
Tier 2 (Sampling-enriched LLM judgment on `rule.applies_when`) lands in v0.11.3.x for clients that support Sampling.
|
|
71
|
+
**Tier 1** (deterministic, every client): action matched against `rule.matches` regex, filtered by `rule.enforce_on`. Hard violations block. Soft violations warn. Approved actions get a fresh receipt with 60s TTL.
|
|
77
72
|
|
|
78
|
-
**
|
|
73
|
+
**Tier 2** (Sampling-enriched, shipped v0.11.7): for rules with `applies_when` natural-language conditions, the server uses MCP Sampling to ask the client's LLM whether the proposed action triggers the rule. Falls back to Tier 1 only if the client doesn't advertise Sampling capability. Works on Claude Desktop and VS Code Copilot; on Claude Code, Cursor, Cline, and Codex CLI you get Tier 1 only — which is enough to enforce the rules you've written.
|
|
79
74
|
|
|
80
|
-
### Compliance Receipts
|
|
75
|
+
### 3. Compliance Receipts · the cryptographic primitive
|
|
81
76
|
|
|
82
|
-
Receipts are short-lived,
|
|
77
|
+
Receipts are short-lived, signed bearer tokens with caveats (Macaroon pattern · [Birgisson et al., NDSS 2014](https://research.google/pubs/pub41892/)). The novel protocol primitive: server-issued tokens that bind to action + session + rules-version-hash + expiry. Tampering breaks the signature. Rule changes invalidate every outstanding receipt (because `rules_version` is part of the signed payload).
|
|
83
78
|
|
|
84
79
|
```typescript
|
|
85
80
|
import { issueReceipt, validateReceipt } from "@xultrax-web/agent-memory-mcp";
|
|
86
81
|
|
|
87
|
-
// Server-internal: issue a receipt for a destructive action
|
|
88
82
|
const r = issueReceipt({
|
|
89
83
|
caveats: [
|
|
90
84
|
{ type: "action", value: "delete_memory" },
|
|
@@ -93,18 +87,17 @@ const r = issueReceipt({
|
|
|
93
87
|
ttl_seconds: 60,
|
|
94
88
|
});
|
|
95
89
|
|
|
96
|
-
// Later: validate before executing the destructive op
|
|
97
90
|
const v = validateReceipt(r, {
|
|
98
91
|
required_caveats: [{ type: "action", value: "delete_memory" }],
|
|
99
92
|
});
|
|
100
93
|
if (!v.valid) throw new Error(v.reason);
|
|
101
94
|
```
|
|
102
95
|
|
|
103
|
-
|
|
96
|
+
**Receipt-required `delete_memory` (v0.12.0 breaking change):** calling `delete_memory` without a valid receipt is refused. The two-step pattern is `check_action` → `delete_memory(name, receipt)`. The signing-key file lives at `<MEMORY_DIR>/.keyring/hmac-key` (CRP 1.0) or `<MEMORY_DIR>/.keyring/ed25519-priv` (CRP 1.1), `0600` perms on POSIX.
|
|
104
97
|
|
|
105
|
-
|
|
98
|
+
**CRP 1.1 · Ed25519 federation (v0.13.0):** flip `CRP_SIGNING_MODE=ed25519` and the server signs with an asymmetric keypair instead of HMAC. The public key gets published at `<MEMORY_DIR>/.keyring/ed25519-pub`, so other MCP servers can validate your receipts without sharing a secret. The protocol allows cross-server enforcement: server A issues a receipt for "delete X", server B validates and honors it.
|
|
106
99
|
|
|
107
|
-
|
|
100
|
+
### 4. `audit` · operational health for the rule store
|
|
108
101
|
|
|
109
102
|
```bash
|
|
110
103
|
agent-memory audit # pretty colored terminal output
|
|
@@ -113,24 +106,17 @@ agent-memory audit --json # structured JSON for tooling
|
|
|
113
106
|
|
|
114
107
|
Surfaces:
|
|
115
108
|
|
|
116
|
-
- Rule count
|
|
117
|
-
- **Stale rules** · `last_verified` > 90 days
|
|
118
|
-
- **Pattern conflicts** · two rules sharing an `enforce_on`
|
|
119
|
-
- **Recent denials** · `check_action` calls that blocked an action (
|
|
120
|
-
- **Unreceipted destructive ops** ·
|
|
121
|
-
|
|
122
|
-
The `healthy` flag is true iff no stale rules, no conflicts, no unreceipted ops in the recent log.
|
|
123
|
-
|
|
124
|
-
### Compliance Receipt Protocol 1.0 spec (v0.11.5)
|
|
125
|
-
|
|
126
|
-
The CRP enforcement primitive is documented as a standalone spec at [docs/compliance-receipt-protocol-1.0.md](docs/compliance-receipt-protocol-1.0.md). Other MCP servers can adopt the same receipt format + validation rules to interoperate · `agent-memory-mcp` is the reference implementation.
|
|
109
|
+
- Rule count by severity (hard / soft / unspecified)
|
|
110
|
+
- **Stale rules** · `last_verified` > 90 days, or never verified
|
|
111
|
+
- **Pattern conflicts** · two rules sharing an `enforce_on` AND an identical regex in `matches`
|
|
112
|
+
- **Recent denials** · `check_action` calls that blocked an action (spot over-aggressive rules)
|
|
113
|
+
- **Unreceipted destructive ops** · should be empty in v0.12+; non-empty means a client is calling `delete_memory` without going through `check_action`
|
|
127
114
|
|
|
128
|
-
The
|
|
115
|
+
The `healthy` flag is true iff no stale rules, no conflicts, no unreceipted ops.
|
|
129
116
|
|
|
130
|
-
###
|
|
117
|
+
### 5. CRP 1.0 / 1.1 as a portable spec
|
|
131
118
|
|
|
132
|
-
|
|
133
|
-
- Repositioning · README hero rewrite, /labs/agent-memory/ page, npm description (v0.11.6)
|
|
119
|
+
The receipt protocol is documented standalone at [docs/compliance-receipt-protocol-1.0.md](docs/compliance-receipt-protocol-1.0.md). Other MCP servers can adopt the same format + validation rules to interoperate · `agent-memory-mcp` is the reference implementation. The spec covers: receipt structure, canonical encoding, signing (HMAC-SHA256 for 1.0, Ed25519 for 1.1), validation order, rules-version hashing, reserved caveat types, MCP integration patterns, security considerations, cross-server adoption, and test vectors.
|
|
134
120
|
|
|
135
121
|
---
|
|
136
122
|
|
|
@@ -311,7 +297,7 @@ Custom path:
|
|
|
311
297
|
| `relevant_memories` | Same matching as search, but returns full memory bodies as one markdown doc. Built for LLM auto-context. |
|
|
312
298
|
| `get_memory` | Fetch one memory by name. Returns frontmatter + body. |
|
|
313
299
|
| `list_memories` | List memories. Optional `type` filter. Paginated (default 50/page). |
|
|
314
|
-
| `delete_memory` |
|
|
300
|
+
| `delete_memory` | **v0.12+: receipt-required.** Pass a valid Compliance Receipt with `{type:'action_type', value:'deletions'}`. Soft-deletes to `.trash/<ts>-<name>.md` on success. |
|
|
315
301
|
| `restore_memory` | Restore a soft-deleted memory from `.trash/`. Picks the most recent trash entry for the name. |
|
|
316
302
|
| `doctor` | Storage integrity check. Reports orphans, dangling index entries, unreadable files. Pass `rebuild-index=true` to repair `MEMORY.md` from disk. |
|
|
317
303
|
| `stats` | Dashboard: counts per type, total size, largest memory, audit-log size, trash count. |
|
|
@@ -322,6 +308,11 @@ Custom path:
|
|
|
322
308
|
| `sync_status` | Report git-sync state: remote URL, branch, uncommitted local files, ahead/behind origin. |
|
|
323
309
|
| `sync_push` | Commit local memory changes + push to the configured git remote. Auto-timestamps the commit message if none given. |
|
|
324
310
|
| `sync_pull` | Fast-forward pull from the git remote. Refuses to pull if local changes are uncommitted. |
|
|
311
|
+
| `save_rule` | **v0.11+.** Create or update a `rule` memory with `severity` / `scope` / `matches` / `enforce_on` / `applies_when` / `last_verified`. Auto-emits companions if configured. |
|
|
312
|
+
| `list_rules` | **v0.11+.** List just rule memories, optionally filtered by severity or enforce_on category. |
|
|
313
|
+
| `emit_companions` | **v0.11.1+.** Project the rule store out to `AGENTS.md` + `CLAUDE.md` + `.cursor/rules/*.mdc` + `.gemini/instructions.md`. Pass `target` to filter. |
|
|
314
|
+
| `check_action` | **v0.11.3+.** Tier-1 deterministic + Tier-2 Sampling rule check. Returns `{approved, hard_violations, soft_warnings, receipt?}`. The protocol enforcement point. |
|
|
315
|
+
| `audit` | **v0.11.4+.** Operational health for the rule store: stale rules, pattern conflicts, recent denials, unreceipted destructive ops. Returns JSON or pretty-prints. |
|
|
325
316
|
|
|
326
317
|
### Prompts
|
|
327
318
|
|
|
@@ -336,12 +327,13 @@ The server exposes 4 built-in MCP prompts that clients (Claude Desktop, Cursor,
|
|
|
336
327
|
|
|
337
328
|
### Memory types
|
|
338
329
|
|
|
339
|
-
|
|
330
|
+
Five built-in types. The first four match the Claude Code convention; `rule` is what v0.11 added:
|
|
340
331
|
|
|
341
332
|
- **user** — facts about the person (role, preferences, expertise level)
|
|
342
|
-
- **feedback** —
|
|
333
|
+
- **feedback** — soft guidance for the assistant (prefer this style, lean toward that approach)
|
|
343
334
|
- **project** — current-state context that isn't in the code (deadlines, in-flight work)
|
|
344
335
|
- **reference** — pointers to external systems (Linear board URL, monitoring dashboard)
|
|
336
|
+
- **rule** — constraints to enforce, not just facts to recall. Carries `severity`, `scope`, `matches`, `enforce_on`, `applies_when`, `last_verified`. Projects to companion files; gates `check_action`.
|
|
345
337
|
|
|
346
338
|
### Tags + wiki-links
|
|
347
339
|
|
|
@@ -392,6 +384,17 @@ agent-memory sync push # commit + push local changes
|
|
|
392
384
|
agent-memory sync pull # fast-forward from remote
|
|
393
385
|
agent-memory sync status # local + ahead/behind state
|
|
394
386
|
agent-memory ui # launch the TUI (browse + edit interactively)
|
|
387
|
+
|
|
388
|
+
# v0.11+ · rules and enforcement
|
|
389
|
+
agent-memory save-rule no-emoji --severity hard --enforce-on commits,chat_responses \
|
|
390
|
+
--matches "emoji|:[a-z_]+:" --content "No emojis. Anywhere. Ever."
|
|
391
|
+
agent-memory list-rules # rule memories only
|
|
392
|
+
agent-memory list-rules --severity hard # filter by severity
|
|
393
|
+
agent-memory emit-companions # write AGENTS.md + CLAUDE.md + .cursor/rules + .gemini
|
|
394
|
+
agent-memory emit-companions --target agents,claude # filter targets
|
|
395
|
+
agent-memory check-action "delete old notes" --type deletions # returns approval + receipt JSON
|
|
396
|
+
agent-memory audit # pretty operational health report
|
|
397
|
+
agent-memory audit --json # structured JSON for tooling
|
|
395
398
|
```
|
|
396
399
|
|
|
397
400
|
### Multi-machine memory (git sync)
|
|
@@ -548,12 +551,28 @@ This server is built to be used daily, not to demo well once.
|
|
|
548
551
|
- Detail pane previews the body of the selected memory
|
|
549
552
|
- Color-coded by type, tag chips inline
|
|
550
553
|
|
|
551
|
-
**
|
|
554
|
+
**Shipped in v0.11 · memory as constraint:**
|
|
555
|
+
|
|
556
|
+
- `rule` memory type with `severity` / `scope` / `matches` / `enforce_on` / `applies_when` / `last_verified`
|
|
557
|
+
- `save_rule` + `list_rules` tools and CLI commands
|
|
558
|
+
- `emit_companions` projects rules to `AGENTS.md` + `CLAUDE.md` + `.cursor/rules/*.mdc` + `.gemini/instructions.md`
|
|
559
|
+
- `AGENT_MEMORY_AUTO_EMIT_DIR` triggers re-emission on every rule save
|
|
560
|
+
- **Compliance Receipts** (`issueReceipt` / `validateReceipt`) — HMAC-SHA256 bearer tokens with Macaroon-style caveats, bound to `rules_version` so rule changes invalidate outstanding tokens
|
|
561
|
+
- `check_action` MCP tool (Tier 1 deterministic; Tier 2 Sampling-enriched on v0.11.7 for clients that advertise the capability)
|
|
562
|
+
- `audit` command — stale rules, pattern conflicts, recent denials, unreceipted destructive ops
|
|
563
|
+
- [CRP 1.0 protocol spec](docs/compliance-receipt-protocol-1.0.md) — portable, vendor-neutral
|
|
564
|
+
|
|
565
|
+
**Shipped in v0.12 · the wedge made teeth (breaking change):**
|
|
566
|
+
|
|
567
|
+
- `delete_memory` REQUIRES a valid receipt. Calling without one is refused at the tool boundary.
|
|
568
|
+
- Two-step pattern is canonical: `check_action` → receipt → `delete_memory(name, receipt)`
|
|
569
|
+
- Audit log no longer needs an "unreceipted ops" warning class to surface escapes — there are none
|
|
570
|
+
|
|
571
|
+
**Shipped in v0.13 · cross-server federation:**
|
|
552
572
|
|
|
553
|
-
-
|
|
554
|
-
-
|
|
555
|
-
-
|
|
556
|
-
- Auto-context loading (LLM gets relevant memories transparently before each prompt)
|
|
573
|
+
- CRP 1.1 · Ed25519 asymmetric signing (set `CRP_SIGNING_MODE=ed25519`)
|
|
574
|
+
- Public key published at `<MEMORY_DIR>/.keyring/ed25519-pub` so other servers can validate without sharing a secret
|
|
575
|
+
- 9 dedicated Ed25519 tests verifying keypair generation, signing, and cross-server validation paths
|
|
557
576
|
|
|
558
577
|
---
|
|
559
578
|
|
|
@@ -572,16 +591,28 @@ This server is built to be used daily, not to demo well once.
|
|
|
572
591
|
| v0.7 | MCP Prompts (4 starter workflows), `verify_memory`, conflict detection on save |
|
|
573
592
|
| v0.8 | Tags, `[[wiki-links]]`, `find_backlinks`, `find_related` |
|
|
574
593
|
| v0.8.1 | Trusted Publishing live · tokenless OIDC publishes to npm + MCP Registry on git tag |
|
|
575
|
-
|
|
|
576
|
-
|
|
|
594
|
+
| v0.9 | `agent-memory sync` · multi-machine memory via git remote (init/push/pull/status/log) |
|
|
595
|
+
| v0.10 | Ink-based TUI · `agent-memory ui` for visual browsing, search, and editing |
|
|
596
|
+
| v0.11.0 | `rule` memory type + `AGENTS.md` companion emitter |
|
|
597
|
+
| v0.11.1 | `CLAUDE.md` + `.cursor/rules/*.mdc` + `.gemini/instructions.md` emitters |
|
|
598
|
+
| v0.11.2 | Compliance Receipts primitive · HMAC-SHA256 tokens with Macaroon-style caveats |
|
|
599
|
+
| v0.11.3 | `check_action` MCP tool (Tier 1 deterministic) + receipt-gated `delete_memory` (opt-in) |
|
|
600
|
+
| v0.11.4 | `audit` command · stale rules, pattern conflicts, recent denials, unreceipted ops |
|
|
601
|
+
| v0.11.5 | CRP 1.0 protocol spec — portable, vendor-neutral enforcement primitive |
|
|
602
|
+
| v0.11.6 | Repositioning · "codify how you work, every AI tool obeys" |
|
|
603
|
+
| v0.11.7 | Tier-2 Sampling-enriched `check_action` · LLM judges `applies_when` on capable clients |
|
|
604
|
+
| **v0.12** | **Receipt REQUIRED on `delete_memory` · breaking change · the wedge made teeth** |
|
|
605
|
+
| **v0.13** | **CRP 1.1 · Ed25519 asymmetric signing for cross-server federation** |
|
|
577
606
|
|
|
578
607
|
### Coming next
|
|
579
608
|
|
|
580
|
-
-
|
|
581
|
-
-
|
|
609
|
+
- Receipt-gated `restore_memory` and `doctor --rebuild-index` (same `check_action` flow)
|
|
610
|
+
- Federation example · a second reference MCP server that issues + validates CRP 1.1 receipts
|
|
611
|
+
- Auto-context loading — server hook that auto-fires `relevant_memories` before each LLM turn
|
|
612
|
+
- Folder support inside the store (`.agent-memory/work/`, `.agent-memory/personal/`)
|
|
582
613
|
- Memory packs — export/import shareable `.tar.gz` bundles of curated memories
|
|
583
|
-
- Browser companion UI (`agent-memory web`)
|
|
584
|
-
- TUI polish — file-watching for auto-refresh, inline editing, sync
|
|
614
|
+
- Browser companion UI (`agent-memory web`)
|
|
615
|
+
- TUI polish — file-watching for auto-refresh, inline editing, sync as keybindings
|
|
585
616
|
|
|
586
617
|
### Beyond
|
|
587
618
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@xultrax-web/agent-memory-mcp",
|
|
3
|
-
"version": "0.13.
|
|
3
|
+
"version": "0.13.2",
|
|
4
4
|
"mcpName": "io.github.xultrax-web/agent-memory-mcp",
|
|
5
5
|
"description": "Codify how you work. Every AI tool obeys. Markdown rules + cross-tool companion files (AGENTS.md/CLAUDE.md/.cursor/rules/.gemini) + Compliance Receipts for protocol-level enforcement of destructive ops. Reference implementation of CRP 1.0. Works on every MCP client (no Sampling required).",
|
|
6
6
|
"type": "module",
|