memwall 0.4.0__tar.gz
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.
- memwall-0.4.0/LICENSE +21 -0
- memwall-0.4.0/PKG-INFO +221 -0
- memwall-0.4.0/README.md +197 -0
- memwall-0.4.0/memwall/__init__.py +10 -0
- memwall-0.4.0/memwall/__main__.py +4 -0
- memwall-0.4.0/memwall/adapters/__init__.py +81 -0
- memwall-0.4.0/memwall/adapters/files.py +50 -0
- memwall-0.4.0/memwall/adapters/generic_json.py +39 -0
- memwall-0.4.0/memwall/adapters/mcp_memory.py +41 -0
- memwall-0.4.0/memwall/adapters/mem0_export.py +43 -0
- memwall-0.4.0/memwall/baseline.py +31 -0
- memwall-0.4.0/memwall/cli.py +235 -0
- memwall-0.4.0/memwall/gateway.py +210 -0
- memwall-0.4.0/memwall/heuristics.py +115 -0
- memwall-0.4.0/memwall/judge.py +86 -0
- memwall-0.4.0/memwall/mcp_client.py +63 -0
- memwall-0.4.0/memwall/models.py +61 -0
- memwall-0.4.0/memwall/policy.py +43 -0
- memwall-0.4.0/memwall/report.py +123 -0
- memwall-0.4.0/memwall/state.py +92 -0
- memwall-0.4.0/memwall.egg-info/PKG-INFO +221 -0
- memwall-0.4.0/memwall.egg-info/SOURCES.txt +32 -0
- memwall-0.4.0/memwall.egg-info/dependency_links.txt +1 -0
- memwall-0.4.0/memwall.egg-info/entry_points.txt +2 -0
- memwall-0.4.0/memwall.egg-info/requires.txt +6 -0
- memwall-0.4.0/memwall.egg-info/top_level.txt +1 -0
- memwall-0.4.0/pyproject.toml +35 -0
- memwall-0.4.0/setup.cfg +4 -0
- memwall-0.4.0/tests/test_adapters.py +49 -0
- memwall-0.4.0/tests/test_cli.py +66 -0
- memwall-0.4.0/tests/test_gateway.py +179 -0
- memwall-0.4.0/tests/test_heuristics.py +62 -0
- memwall-0.4.0/tests/test_policy.py +36 -0
- memwall-0.4.0/tests/test_state.py +69 -0
memwall-0.4.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Gary Bayer Valdivia
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
memwall-0.4.0/PKG-INFO
ADDED
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: memwall
|
|
3
|
+
Version: 0.4.0
|
|
4
|
+
Summary: Scanner for AI agent memory stores: detects memory poisoning, injected instructions, and hygiene issues.
|
|
5
|
+
Author-email: Gary Bayer Valdivia <ggbayervaldivia@gmail.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/gbayerv26/memwall
|
|
8
|
+
Project-URL: Issues, https://github.com/gbayerv26/memwall/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/gbayerv26/memwall/blob/master/CHANGELOG.md
|
|
10
|
+
Keywords: ai-agents,security,memory,memory-poisoning,prompt-injection,llm
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Topic :: Security
|
|
16
|
+
Requires-Python: >=3.9
|
|
17
|
+
Description-Content-Type: text/markdown
|
|
18
|
+
License-File: LICENSE
|
|
19
|
+
Provides-Extra: judge
|
|
20
|
+
Requires-Dist: anthropic>=0.40; extra == "judge"
|
|
21
|
+
Provides-Extra: dev
|
|
22
|
+
Requires-Dist: pytest; extra == "dev"
|
|
23
|
+
Dynamic: license-file
|
|
24
|
+
|
|
25
|
+
# memwall
|
|
26
|
+
|
|
27
|
+

|
|
28
|
+

|
|
29
|
+

|
|
30
|
+
|
|
31
|
+
**Antivirus for AI agent memory.**
|
|
32
|
+
|
|
33
|
+
Persistent memory is the newest attack surface in agentic AI. One poisoned
|
|
34
|
+
memory — planted through an email, a webpage, or a document your agent read —
|
|
35
|
+
survives across sessions and fires days or weeks later. OWASP added *Memory
|
|
36
|
+
and Context Poisoning* to its 2026 Agentic AI Top 10 (ASI06); published
|
|
37
|
+
research shows attack success rates of 80–99% against real agent stacks.
|
|
38
|
+
|
|
39
|
+
memwall scans agent memory stores for injected standing orders, exfiltration
|
|
40
|
+
vectors, hidden payloads, and hygiene issues like retained PII. Zero
|
|
41
|
+
dependencies for the core scan.
|
|
42
|
+
|
|
43
|
+
## Quickstart
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
pip install -e .
|
|
47
|
+
|
|
48
|
+
memwall scan path/to/memory.json # one store or export
|
|
49
|
+
memwall scan . # walk a project: CLAUDE.md, AGENTS.md, memory files
|
|
50
|
+
memwall scan memory.json --judge # add the Claude semantic judge (needs ANTHROPIC_API_KEY)
|
|
51
|
+
memwall rules # list detection rules
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
60-second demo — scan the bundled example store and watch it catch an
|
|
55
|
+
invoice-exfiltration implant and a payment redirect:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
git clone https://github.com/gbayerv26/memwall && cd memwall
|
|
59
|
+
pip install -e .
|
|
60
|
+
memwall scan examples/
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Directory scans are memory-aware: `package.json`, `tsconfig.json`, and other
|
|
64
|
+
non-memory JSON are skipped automatically, as are files over 5 MB.
|
|
65
|
+
|
|
66
|
+
## Supported stores (v0.1)
|
|
67
|
+
|
|
68
|
+
- **MCP reference memory server** — `memory.json` / `.jsonl` of entities and observations
|
|
69
|
+
- **mem0-style exports** — JSON lists of memory objects
|
|
70
|
+
- **Agent instruction files** — `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursorrules`, `.mdc`
|
|
71
|
+
- **Notes / markdown memory files** and generic JSON dumps
|
|
72
|
+
|
|
73
|
+
## How it works
|
|
74
|
+
|
|
75
|
+
**Pass 1 — heuristics (free, instant).** Rules MW001–MW013 catch the known
|
|
76
|
+
shapes of memory poisoning: instruction overrides, secrecy pressure
|
|
77
|
+
("don't tell the user"), authority claims ("system note:", "developer mode"),
|
|
78
|
+
payment redirection, crypto wallets, encoded payloads, zero-width/bidi hidden
|
|
79
|
+
characters, and PII that needs an expiry policy. A combo rule (MW000)
|
|
80
|
+
escalates to CRITICAL when a standing order and an outbound destination appear
|
|
81
|
+
in the same memory — the classic exfiltration shape.
|
|
82
|
+
|
|
83
|
+
Instruction files get a calibrated ruleset: imperatives are normal in a
|
|
84
|
+
CLAUDE.md, so only the genuinely suspicious rules apply there.
|
|
85
|
+
|
|
86
|
+
**Pass 2 — the judge (optional).** `--judge` sends flagged records to Claude
|
|
87
|
+
for semantic classification (`benign_fact` / `preference` / `task_context` /
|
|
88
|
+
`suspicious_instruction` / `likely_injection`). The judge treats memory
|
|
89
|
+
content as untrusted data and never follows instructions inside it.
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
pip install -e ".[judge]"
|
|
93
|
+
export ANTHROPIC_API_KEY=sk-ant-...
|
|
94
|
+
memwall scan memory.json --judge
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## CI gate
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
memwall scan ./agent-memory --fail-on high --json memwall-report.json
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Exit code is 1 when any finding meets the `--fail-on` threshold, so you can
|
|
104
|
+
block deploys on a poisoned store.
|
|
105
|
+
|
|
106
|
+
Accepted findings can be baselined so CI only fails on **new** ones — a
|
|
107
|
+
baselined finding stays suppressed until the memory content itself changes:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
memwall scan ./agent-memory --baseline .memwall-baseline.json --update-baseline # accept current state
|
|
111
|
+
memwall scan ./agent-memory --baseline .memwall-baseline.json --fail-on high -q # gate on new findings
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## The gateway — quarantine before commit
|
|
115
|
+
|
|
116
|
+
`memwall gateway` is a transparent MCP proxy you put in front of any stdio
|
|
117
|
+
memory server. Every memory write is scanned *before* it reaches the store;
|
|
118
|
+
anything at or above the block threshold is quarantined instead of written,
|
|
119
|
+
and the agent gets a clear "blocked, do not retry" tool response. Reads and
|
|
120
|
+
all other traffic pass through untouched.
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
memwall gateway --state-dir ~/.memwall -- npx -y @modelcontextprotocol/server-memory
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Claude Desktop / Claude Code config — wrap your existing memory server:
|
|
127
|
+
|
|
128
|
+
```json
|
|
129
|
+
{
|
|
130
|
+
"mcpServers": {
|
|
131
|
+
"memory": {
|
|
132
|
+
"command": "memwall",
|
|
133
|
+
"args": ["gateway", "--state-dir", "/home/you/.memwall", "--",
|
|
134
|
+
"npx", "-y", "@modelcontextprotocol/server-memory"]
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Writes (tool names matching create/add/store/save/write/update/remember/...)
|
|
141
|
+
are scanned with the same rule engine as `memwall scan`. The gateway fails
|
|
142
|
+
open on internal errors and keeps protocol traffic on stdout and diagnostics
|
|
143
|
+
on stderr, so it never takes your memory server down.
|
|
144
|
+
|
|
145
|
+
Review what happened — every write is recorded in an append-only audit trail
|
|
146
|
+
with a payload hash, so you can answer "when did this belief enter memory":
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
memwall log --state-dir ~/.memwall # forensic event log
|
|
150
|
+
memwall quarantine --state-dir ~/.memwall list # held writes
|
|
151
|
+
memwall quarantine --state-dir ~/.memwall show q1a2b3c4
|
|
152
|
+
memwall quarantine --state-dir ~/.memwall release q1a2b3c4 -- npx -y @modelcontextprotocol/server-memory
|
|
153
|
+
memwall quarantine --state-dir ~/.memwall drop q1a2b3c4
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
`release` replays the original write to the backend after human review;
|
|
157
|
+
`drop` discards it. Both decisions are appended to the audit trail, never
|
|
158
|
+
rewritten over it.
|
|
159
|
+
|
|
160
|
+
## Trust-aware policies — the provenance handshake
|
|
161
|
+
|
|
162
|
+
Agents (or their harnesses) can declare where memory content came from by
|
|
163
|
+
attaching MCP metadata to the write call:
|
|
164
|
+
|
|
165
|
+
```json
|
|
166
|
+
{"method": "tools/call",
|
|
167
|
+
"params": {"name": "add_observations",
|
|
168
|
+
"_meta": {"memwall": {"origin": "web"}},
|
|
169
|
+
"arguments": {"...": "..."}}}
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
Each origin maps to a block threshold — content from the open web is held to
|
|
173
|
+
a stricter bar than something the user typed:
|
|
174
|
+
|
|
175
|
+
| origin | blocks at |
|
|
176
|
+
|---|---|
|
|
177
|
+
| `user` | critical |
|
|
178
|
+
| `agent` | high |
|
|
179
|
+
| `tool` / `web` / `email` / `document` | medium |
|
|
180
|
+
| undeclared | `--block-at` (default high) |
|
|
181
|
+
|
|
182
|
+
Override with `--policy policy.json`:
|
|
183
|
+
|
|
184
|
+
```json
|
|
185
|
+
{"default_block_at": "high", "origins": {"web": "low", "voicemail": "low"}}
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
Unlisted origins keep the built-in table. The declared origin is recorded on
|
|
189
|
+
every event and quarantine entry, so the audit trail carries provenance. The
|
|
190
|
+
`memwall` meta key is stripped before the call reaches the backend.
|
|
191
|
+
|
|
192
|
+
## Judge-in-the-loop
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
memwall gateway --judge -- npx -y @modelcontextprotocol/server-memory
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
With `--judge`, flagged writes get a second opinion from the Claude judge
|
|
199
|
+
before quarantining. Clearing verdicts (fact / preference / task context) let
|
|
200
|
+
the write through — cutting heuristic false positives without losing the
|
|
201
|
+
block on real injections. If the judge is unavailable or unsure, the write
|
|
202
|
+
stays quarantined (fail-safe). Needs `pip install "memwall[judge]"` and
|
|
203
|
+
`ANTHROPIC_API_KEY`; adds one API call only to writes heuristics already
|
|
204
|
+
flagged, so normal traffic pays zero latency.
|
|
205
|
+
|
|
206
|
+
## Roadmap
|
|
207
|
+
|
|
208
|
+
- **Phase 3 — hosted monitoring.** Continuous scans, alerting, and compliance
|
|
209
|
+
exports (EU AI Act logging, GDPR erasure verification).
|
|
210
|
+
- More stores: Zep, Letta, LangGraph checkpoints, vector DBs.
|
|
211
|
+
- Policy packs: shareable, versioned policies per industry / risk appetite.
|
|
212
|
+
|
|
213
|
+
## Honest limitations
|
|
214
|
+
|
|
215
|
+
Heuristics have false positives and false negatives by design — they are a
|
|
216
|
+
triage layer, not a verdict. Review findings before deleting memories. The
|
|
217
|
+
judge pass improves precision but is only as good as the model behind it.
|
|
218
|
+
|
|
219
|
+
## License
|
|
220
|
+
|
|
221
|
+
MIT
|
memwall-0.4.0/README.md
ADDED
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
# memwall
|
|
2
|
+
|
|
3
|
+

|
|
4
|
+

|
|
5
|
+

|
|
6
|
+
|
|
7
|
+
**Antivirus for AI agent memory.**
|
|
8
|
+
|
|
9
|
+
Persistent memory is the newest attack surface in agentic AI. One poisoned
|
|
10
|
+
memory — planted through an email, a webpage, or a document your agent read —
|
|
11
|
+
survives across sessions and fires days or weeks later. OWASP added *Memory
|
|
12
|
+
and Context Poisoning* to its 2026 Agentic AI Top 10 (ASI06); published
|
|
13
|
+
research shows attack success rates of 80–99% against real agent stacks.
|
|
14
|
+
|
|
15
|
+
memwall scans agent memory stores for injected standing orders, exfiltration
|
|
16
|
+
vectors, hidden payloads, and hygiene issues like retained PII. Zero
|
|
17
|
+
dependencies for the core scan.
|
|
18
|
+
|
|
19
|
+
## Quickstart
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
pip install -e .
|
|
23
|
+
|
|
24
|
+
memwall scan path/to/memory.json # one store or export
|
|
25
|
+
memwall scan . # walk a project: CLAUDE.md, AGENTS.md, memory files
|
|
26
|
+
memwall scan memory.json --judge # add the Claude semantic judge (needs ANTHROPIC_API_KEY)
|
|
27
|
+
memwall rules # list detection rules
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
60-second demo — scan the bundled example store and watch it catch an
|
|
31
|
+
invoice-exfiltration implant and a payment redirect:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
git clone https://github.com/gbayerv26/memwall && cd memwall
|
|
35
|
+
pip install -e .
|
|
36
|
+
memwall scan examples/
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Directory scans are memory-aware: `package.json`, `tsconfig.json`, and other
|
|
40
|
+
non-memory JSON are skipped automatically, as are files over 5 MB.
|
|
41
|
+
|
|
42
|
+
## Supported stores (v0.1)
|
|
43
|
+
|
|
44
|
+
- **MCP reference memory server** — `memory.json` / `.jsonl` of entities and observations
|
|
45
|
+
- **mem0-style exports** — JSON lists of memory objects
|
|
46
|
+
- **Agent instruction files** — `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursorrules`, `.mdc`
|
|
47
|
+
- **Notes / markdown memory files** and generic JSON dumps
|
|
48
|
+
|
|
49
|
+
## How it works
|
|
50
|
+
|
|
51
|
+
**Pass 1 — heuristics (free, instant).** Rules MW001–MW013 catch the known
|
|
52
|
+
shapes of memory poisoning: instruction overrides, secrecy pressure
|
|
53
|
+
("don't tell the user"), authority claims ("system note:", "developer mode"),
|
|
54
|
+
payment redirection, crypto wallets, encoded payloads, zero-width/bidi hidden
|
|
55
|
+
characters, and PII that needs an expiry policy. A combo rule (MW000)
|
|
56
|
+
escalates to CRITICAL when a standing order and an outbound destination appear
|
|
57
|
+
in the same memory — the classic exfiltration shape.
|
|
58
|
+
|
|
59
|
+
Instruction files get a calibrated ruleset: imperatives are normal in a
|
|
60
|
+
CLAUDE.md, so only the genuinely suspicious rules apply there.
|
|
61
|
+
|
|
62
|
+
**Pass 2 — the judge (optional).** `--judge` sends flagged records to Claude
|
|
63
|
+
for semantic classification (`benign_fact` / `preference` / `task_context` /
|
|
64
|
+
`suspicious_instruction` / `likely_injection`). The judge treats memory
|
|
65
|
+
content as untrusted data and never follows instructions inside it.
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
pip install -e ".[judge]"
|
|
69
|
+
export ANTHROPIC_API_KEY=sk-ant-...
|
|
70
|
+
memwall scan memory.json --judge
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## CI gate
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
memwall scan ./agent-memory --fail-on high --json memwall-report.json
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Exit code is 1 when any finding meets the `--fail-on` threshold, so you can
|
|
80
|
+
block deploys on a poisoned store.
|
|
81
|
+
|
|
82
|
+
Accepted findings can be baselined so CI only fails on **new** ones — a
|
|
83
|
+
baselined finding stays suppressed until the memory content itself changes:
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
memwall scan ./agent-memory --baseline .memwall-baseline.json --update-baseline # accept current state
|
|
87
|
+
memwall scan ./agent-memory --baseline .memwall-baseline.json --fail-on high -q # gate on new findings
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## The gateway — quarantine before commit
|
|
91
|
+
|
|
92
|
+
`memwall gateway` is a transparent MCP proxy you put in front of any stdio
|
|
93
|
+
memory server. Every memory write is scanned *before* it reaches the store;
|
|
94
|
+
anything at or above the block threshold is quarantined instead of written,
|
|
95
|
+
and the agent gets a clear "blocked, do not retry" tool response. Reads and
|
|
96
|
+
all other traffic pass through untouched.
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
memwall gateway --state-dir ~/.memwall -- npx -y @modelcontextprotocol/server-memory
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Claude Desktop / Claude Code config — wrap your existing memory server:
|
|
103
|
+
|
|
104
|
+
```json
|
|
105
|
+
{
|
|
106
|
+
"mcpServers": {
|
|
107
|
+
"memory": {
|
|
108
|
+
"command": "memwall",
|
|
109
|
+
"args": ["gateway", "--state-dir", "/home/you/.memwall", "--",
|
|
110
|
+
"npx", "-y", "@modelcontextprotocol/server-memory"]
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Writes (tool names matching create/add/store/save/write/update/remember/...)
|
|
117
|
+
are scanned with the same rule engine as `memwall scan`. The gateway fails
|
|
118
|
+
open on internal errors and keeps protocol traffic on stdout and diagnostics
|
|
119
|
+
on stderr, so it never takes your memory server down.
|
|
120
|
+
|
|
121
|
+
Review what happened — every write is recorded in an append-only audit trail
|
|
122
|
+
with a payload hash, so you can answer "when did this belief enter memory":
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
memwall log --state-dir ~/.memwall # forensic event log
|
|
126
|
+
memwall quarantine --state-dir ~/.memwall list # held writes
|
|
127
|
+
memwall quarantine --state-dir ~/.memwall show q1a2b3c4
|
|
128
|
+
memwall quarantine --state-dir ~/.memwall release q1a2b3c4 -- npx -y @modelcontextprotocol/server-memory
|
|
129
|
+
memwall quarantine --state-dir ~/.memwall drop q1a2b3c4
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
`release` replays the original write to the backend after human review;
|
|
133
|
+
`drop` discards it. Both decisions are appended to the audit trail, never
|
|
134
|
+
rewritten over it.
|
|
135
|
+
|
|
136
|
+
## Trust-aware policies — the provenance handshake
|
|
137
|
+
|
|
138
|
+
Agents (or their harnesses) can declare where memory content came from by
|
|
139
|
+
attaching MCP metadata to the write call:
|
|
140
|
+
|
|
141
|
+
```json
|
|
142
|
+
{"method": "tools/call",
|
|
143
|
+
"params": {"name": "add_observations",
|
|
144
|
+
"_meta": {"memwall": {"origin": "web"}},
|
|
145
|
+
"arguments": {"...": "..."}}}
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Each origin maps to a block threshold — content from the open web is held to
|
|
149
|
+
a stricter bar than something the user typed:
|
|
150
|
+
|
|
151
|
+
| origin | blocks at |
|
|
152
|
+
|---|---|
|
|
153
|
+
| `user` | critical |
|
|
154
|
+
| `agent` | high |
|
|
155
|
+
| `tool` / `web` / `email` / `document` | medium |
|
|
156
|
+
| undeclared | `--block-at` (default high) |
|
|
157
|
+
|
|
158
|
+
Override with `--policy policy.json`:
|
|
159
|
+
|
|
160
|
+
```json
|
|
161
|
+
{"default_block_at": "high", "origins": {"web": "low", "voicemail": "low"}}
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
Unlisted origins keep the built-in table. The declared origin is recorded on
|
|
165
|
+
every event and quarantine entry, so the audit trail carries provenance. The
|
|
166
|
+
`memwall` meta key is stripped before the call reaches the backend.
|
|
167
|
+
|
|
168
|
+
## Judge-in-the-loop
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
memwall gateway --judge -- npx -y @modelcontextprotocol/server-memory
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
With `--judge`, flagged writes get a second opinion from the Claude judge
|
|
175
|
+
before quarantining. Clearing verdicts (fact / preference / task context) let
|
|
176
|
+
the write through — cutting heuristic false positives without losing the
|
|
177
|
+
block on real injections. If the judge is unavailable or unsure, the write
|
|
178
|
+
stays quarantined (fail-safe). Needs `pip install "memwall[judge]"` and
|
|
179
|
+
`ANTHROPIC_API_KEY`; adds one API call only to writes heuristics already
|
|
180
|
+
flagged, so normal traffic pays zero latency.
|
|
181
|
+
|
|
182
|
+
## Roadmap
|
|
183
|
+
|
|
184
|
+
- **Phase 3 — hosted monitoring.** Continuous scans, alerting, and compliance
|
|
185
|
+
exports (EU AI Act logging, GDPR erasure verification).
|
|
186
|
+
- More stores: Zep, Letta, LangGraph checkpoints, vector DBs.
|
|
187
|
+
- Policy packs: shareable, versioned policies per industry / risk appetite.
|
|
188
|
+
|
|
189
|
+
## Honest limitations
|
|
190
|
+
|
|
191
|
+
Heuristics have false positives and false negatives by design — they are a
|
|
192
|
+
triage layer, not a verdict. Review findings before deleting memories. The
|
|
193
|
+
judge pass improves precision but is only as good as the model behind it.
|
|
194
|
+
|
|
195
|
+
## License
|
|
196
|
+
|
|
197
|
+
MIT
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
"""memwall: scanner for AI agent memory stores.
|
|
2
|
+
|
|
3
|
+
Detects memory poisoning (injected standing orders, exfiltration vectors,
|
|
4
|
+
hidden payloads) and hygiene issues (retained PII) in agent memory.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
__version__ = "0.4.0"
|
|
8
|
+
|
|
9
|
+
from .adapters import load # noqa: F401
|
|
10
|
+
from .heuristics import scan_records # noqa: F401
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
"""Store adapters: read memories from different sources into MemoryRecords."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
import os
|
|
5
|
+
import sys
|
|
6
|
+
|
|
7
|
+
from . import files, generic_json, mcp_memory, mem0_export
|
|
8
|
+
|
|
9
|
+
ADAPTERS = {
|
|
10
|
+
"files": files.load,
|
|
11
|
+
"mcp": mcp_memory.load,
|
|
12
|
+
"mem0": mem0_export.load,
|
|
13
|
+
"json": generic_json.load,
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
SKIP_DIRS = {".git", "node_modules", "__pycache__", ".venv", "venv", "dist", "build", ".next"}
|
|
17
|
+
# Hidden dirs are skipped except the ones agents actually keep memory in.
|
|
18
|
+
KEEP_HIDDEN = {".claude", ".codex", ".cursor", ".gemini", ".github"}
|
|
19
|
+
KNOWN_NAMES = {"claude.md", "agents.md", "gemini.md", ".cursorrules", "memory.json", "memory.jsonl"}
|
|
20
|
+
EXTS = {".md", ".mdc", ".txt", ".json", ".jsonl"}
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def detect_format(path: str) -> str:
|
|
24
|
+
ext = os.path.splitext(path)[1].lower()
|
|
25
|
+
if ext == ".jsonl":
|
|
26
|
+
return "mcp"
|
|
27
|
+
if ext == ".json":
|
|
28
|
+
try:
|
|
29
|
+
with open(path, encoding="utf-8-sig") as fh:
|
|
30
|
+
head = fh.read(4096).lstrip()
|
|
31
|
+
except OSError:
|
|
32
|
+
return "json"
|
|
33
|
+
# The MCP reference memory server writes JSONL into a .json file.
|
|
34
|
+
if head.startswith('{"type"') or '"observations"' in head:
|
|
35
|
+
return "mcp"
|
|
36
|
+
if '"memory"' in head or '"results"' in head:
|
|
37
|
+
return "mem0"
|
|
38
|
+
return "json"
|
|
39
|
+
return "files"
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
MAX_WALK_FILE_BYTES = 5 * 1024 * 1024
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def _walkable(file_path: str, low: str, ext: str) -> bool:
|
|
46
|
+
try:
|
|
47
|
+
if os.path.getsize(file_path) > MAX_WALK_FILE_BYTES:
|
|
48
|
+
print(f"memwall: skipped {file_path}: larger than "
|
|
49
|
+
f"{MAX_WALK_FILE_BYTES // (1024 * 1024)} MB", file=sys.stderr)
|
|
50
|
+
return False
|
|
51
|
+
except OSError:
|
|
52
|
+
return False
|
|
53
|
+
if ext == ".json" and low not in KNOWN_NAMES:
|
|
54
|
+
# In directory walks, only ingest .json that looks like agent memory -
|
|
55
|
+
# otherwise every package.json and tsconfig.json becomes noise.
|
|
56
|
+
return "memor" in low or "mem0" in low or detect_format(file_path) != "json"
|
|
57
|
+
return True
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def load(path: str, fmt: str = "auto") -> list:
|
|
61
|
+
if fmt != "auto":
|
|
62
|
+
return ADAPTERS[fmt](path)
|
|
63
|
+
if os.path.isdir(path):
|
|
64
|
+
records = []
|
|
65
|
+
for root, dirs, names in os.walk(path):
|
|
66
|
+
dirs[:] = [d for d in dirs
|
|
67
|
+
if d not in SKIP_DIRS and (not d.startswith(".") or d in KEEP_HIDDEN)]
|
|
68
|
+
for name in sorted(names):
|
|
69
|
+
low = name.lower()
|
|
70
|
+
ext = os.path.splitext(low)[1]
|
|
71
|
+
if low not in KNOWN_NAMES and ext not in EXTS:
|
|
72
|
+
continue
|
|
73
|
+
file_path = os.path.join(root, name)
|
|
74
|
+
if not _walkable(file_path, low, ext):
|
|
75
|
+
continue
|
|
76
|
+
try:
|
|
77
|
+
records.extend(load(file_path, "auto"))
|
|
78
|
+
except Exception as exc: # keep walking on malformed files
|
|
79
|
+
print(f"memwall: skipped {file_path}: {exc}", file=sys.stderr)
|
|
80
|
+
return records
|
|
81
|
+
return ADAPTERS[detect_format(path)](path)
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
"""Adapter for plain text/markdown memory and instruction files.
|
|
2
|
+
|
|
3
|
+
Instruction files (CLAUDE.md, AGENTS.md, ...) are marked kind="instructions"
|
|
4
|
+
so the rule engine can skip imperative-phrasing rules that are normal there.
|
|
5
|
+
Every other text file is kind="notes". Each blank-line-separated block
|
|
6
|
+
becomes one MemoryRecord.
|
|
7
|
+
"""
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import os
|
|
11
|
+
|
|
12
|
+
from ..models import MemoryRecord
|
|
13
|
+
|
|
14
|
+
INSTRUCTION_NAMES = {
|
|
15
|
+
"claude.md", "agents.md", "gemini.md", ".cursorrules",
|
|
16
|
+
"copilot-instructions.md", "system.md",
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def _blocks(text: str):
|
|
21
|
+
block, start = [], 1
|
|
22
|
+
line_no = 0
|
|
23
|
+
for line_no, line in enumerate(text.splitlines(), 1):
|
|
24
|
+
if line.strip():
|
|
25
|
+
if not block:
|
|
26
|
+
start = line_no
|
|
27
|
+
block.append(line)
|
|
28
|
+
elif block:
|
|
29
|
+
yield start, "\n".join(block)
|
|
30
|
+
block = []
|
|
31
|
+
if block:
|
|
32
|
+
yield start, "\n".join(block)
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def load(path: str) -> list:
|
|
36
|
+
with open(path, encoding="utf-8-sig", errors="replace") as fh:
|
|
37
|
+
text = fh.read()
|
|
38
|
+
base = os.path.basename(path)
|
|
39
|
+
low = base.lower()
|
|
40
|
+
kind = "instructions" if low in INSTRUCTION_NAMES or low.endswith(".mdc") else "notes"
|
|
41
|
+
return [
|
|
42
|
+
MemoryRecord(
|
|
43
|
+
id=f"{base}:{line}",
|
|
44
|
+
content=content,
|
|
45
|
+
store="files",
|
|
46
|
+
source=path,
|
|
47
|
+
metadata={"kind": kind},
|
|
48
|
+
)
|
|
49
|
+
for line, content in _blocks(text)
|
|
50
|
+
]
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
"""Fallback adapter for generic JSON memory dumps."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
import json
|
|
5
|
+
|
|
6
|
+
from ..models import MemoryRecord
|
|
7
|
+
|
|
8
|
+
_CONTENT_FIELDS = ("content", "memory", "text", "observation", "value", "fact", "note")
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def load(path: str) -> list:
|
|
12
|
+
with open(path, encoding="utf-8-sig") as fh:
|
|
13
|
+
data = json.load(fh)
|
|
14
|
+
if isinstance(data, dict):
|
|
15
|
+
for key in ("results", "items", "memories", "data", "records"):
|
|
16
|
+
if isinstance(data.get(key), list):
|
|
17
|
+
data = data[key]
|
|
18
|
+
break
|
|
19
|
+
else:
|
|
20
|
+
data = [data]
|
|
21
|
+
if not isinstance(data, list):
|
|
22
|
+
data = [data]
|
|
23
|
+
|
|
24
|
+
records = []
|
|
25
|
+
for idx, item in enumerate(data):
|
|
26
|
+
if isinstance(item, str):
|
|
27
|
+
content = item
|
|
28
|
+
elif isinstance(item, dict):
|
|
29
|
+
content = next((str(item[f]) for f in _CONTENT_FIELDS if item.get(f)), "")
|
|
30
|
+
else:
|
|
31
|
+
continue
|
|
32
|
+
if content:
|
|
33
|
+
records.append(MemoryRecord(
|
|
34
|
+
id=str(item.get("id", f"item-{idx}")) if isinstance(item, dict) else f"item-{idx}",
|
|
35
|
+
content=content,
|
|
36
|
+
store="json",
|
|
37
|
+
source=path,
|
|
38
|
+
))
|
|
39
|
+
return records
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
"""Adapter for the MCP reference memory server (JSONL of entities/relations)."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
import json
|
|
5
|
+
|
|
6
|
+
from ..models import MemoryRecord
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def load(path: str) -> list:
|
|
10
|
+
records = []
|
|
11
|
+
with open(path, encoding="utf-8-sig") as fh:
|
|
12
|
+
for line_no, line in enumerate(fh, 1):
|
|
13
|
+
line = line.strip()
|
|
14
|
+
if not line:
|
|
15
|
+
continue
|
|
16
|
+
try:
|
|
17
|
+
obj = json.loads(line)
|
|
18
|
+
except json.JSONDecodeError:
|
|
19
|
+
continue
|
|
20
|
+
if not isinstance(obj, dict):
|
|
21
|
+
continue
|
|
22
|
+
if obj.get("type") == "entity":
|
|
23
|
+
name = obj.get("name", f"entity-{line_no}")
|
|
24
|
+
for idx, observation in enumerate(obj.get("observations", [])):
|
|
25
|
+
records.append(MemoryRecord(
|
|
26
|
+
id=f"{name}#obs{idx}",
|
|
27
|
+
content=str(observation),
|
|
28
|
+
store="mcp-memory",
|
|
29
|
+
source=path,
|
|
30
|
+
metadata={"entity": name, "entityType": obj.get("entityType")},
|
|
31
|
+
))
|
|
32
|
+
elif obj.get("type") == "relation":
|
|
33
|
+
content = f"{obj.get('from')} {obj.get('relationType')} {obj.get('to')}"
|
|
34
|
+
records.append(MemoryRecord(
|
|
35
|
+
id=f"relation:{line_no}",
|
|
36
|
+
content=content,
|
|
37
|
+
store="mcp-memory",
|
|
38
|
+
source=path,
|
|
39
|
+
metadata={"relation": True},
|
|
40
|
+
))
|
|
41
|
+
return records
|