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 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
+ ![ci](https://github.com/gbayerv26/memwall/actions/workflows/ci.yml/badge.svg)
28
+ ![python](https://img.shields.io/badge/python-3.9%2B-blue)
29
+ ![license](https://img.shields.io/badge/license-MIT-green)
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
@@ -0,0 +1,197 @@
1
+ # memwall
2
+
3
+ ![ci](https://github.com/gbayerv26/memwall/actions/workflows/ci.yml/badge.svg)
4
+ ![python](https://img.shields.io/badge/python-3.9%2B-blue)
5
+ ![license](https://img.shields.io/badge/license-MIT-green)
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,4 @@
1
+ from .cli import run
2
+
3
+ if __name__ == "__main__":
4
+ run()
@@ -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