agentmemorytaintgap 0.1.0__tar.gz

agentmemorytaintgap-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package with dev extras
+        run: pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest tests/ -v

agentmemorytaintgap-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/

agentmemorytaintgap-0.1.0/DETAILS.md

@@ -0,0 +1,193 @@
+# agentmemorytaintgap — DETAILS
+
+## The gap this fills
+
+Prompt injection is usually discussed as a single-turn problem: untrusted
+content (a scraped page, a tool result, a crafted user message) gets built
+into one LLM prompt, and the model's *response* to that one call is what's
+at risk. That's the shape tools like `echofence` cover.
+
+Agent frameworks with **persistent/long-term memory** introduce a different
+failure mode. When an agent explicitly *writes* content into a memory store
+— because the framework encourages "remembering" facts, summaries, or past
+tool results across sessions — that write becomes a trust boundary crossing
+of its own. If the content being written was itself untrusted (attacker- or
+externally-controlled), and it gets stored with no marker distinguishing it
+from the agent's own reasoning, every *future* prompt that reads that memory
+back in treats it as ground truth. The attack surface is not "one bad
+response" — it's "every future response until the memory store is purged or
+the poisoned entry is found."
+
+This is a real, currently-discussed, and distinct risk category. As of
+research current through 2026, multiple papers explicitly separate memory
+poisoning from ordinary (single-turn) prompt injection on exactly this
+timing/persistence axis:
+
+- *"From Untrusted Input to Trusted Memory: A Systematic Study of Memory
+  Poisoning Attacks in LLM Agents"* (arXiv 2606.04329) — memory poisoning
+  lets an adversary insert malicious information into an agent's long-term
+  memory, which then persistently influences future behavior without
+  further attacker involvement, explicitly distinguishing it from
+  traditional single-session prompt injection.
+- *"A Survey on Long-Term Memory Security in LLM Agents: Attacks, Defenses,
+  and Governance Across the Memory Lifecycle"* (arXiv 2604.16548).
+- *"Securing LLM-Agent Long-Term Memory Against Poisoning..."*
+  (arXiv 2606.24322).
+- Industry coverage: OWASP's "Agent Memory Guard" guidance, and vendor posts
+  (WorkOS, Medium/independent security writers) describing memory poisoning
+  as an attack that "waits" — content stored in one session that steers a
+  consequential action weeks later, in a different session.
+
+Existing detection work in this space (e.g. "Ratine", MEMSAD, and similar)
+operates at **runtime**, inspecting the actual content sitting in a live
+memory store / vector database for injected instructions or anomalies.
+Nothing found in that search is a **static, source-code-level AST linter**
+that flags the *write call site itself* — i.e. catches the vulnerable
+pattern in code review, before the agent ever runs, the same way a SAST tool
+catches a SQL-injection-shaped string concatenation before the query ever
+executes. That's the gap `agentmemorytaintgap` fills.
+
+## Honest relationship to echofence (verified, not assumed)
+
+Both tools were built in this workspace and both are prompt-injection
+adjacent, so the distinction needs to be genuine, not cosmetic. This was
+checked against echofence's actual README/DETAILS, not assumed:
+
+- **echofence's scope** (confirmed from its own docs): it flags untrusted
+  *external* content (web scrape, retrieved RAG doc, email/file/PDF text,
+  tool/MCP output) built directly into an **LLM prompt/message sink**
+  (`messages=`, `prompt=`, LangChain message constructors, etc.) with no
+  delimiter/isolation. Its own DETAILS.md explicitly scopes it as the
+  *indirect* OWASP LLM01 variant — external content reaching a prompt.
+  Nothing in echofence's source recognizes memory-store write methods
+  (`save_context`, `chat_memory.add_*`, vector-store `.add`/`.upsert`, or
+  custom `remember`/`store_memory` helpers) as sinks at all — its sink list
+  is specifically LLM call kwargs and chat-message constructors.
+- **agentmemorytaintgap's scope**: the sink is a **memory-write call**, not
+  a prompt-construction call. The artifact produced by a miss is different
+  too — an unflagged echofence gap produces one bad response; an unflagged
+  agentmemorytaintgap gap produces a **persisted, replayable** poisoned
+  memory entry that resurfaces in every subsequent turn that reads that
+  memory back.
+- **They do not overlap in code**: echofence never inspects `.save_context`/
+  `.chat_memory.*`/vector-store `.add`/`.upsert`/`remember`-shaped calls as
+  sinks, and agentmemorytaintgap never inspects `messages=`/`prompt=`
+  LLM-call kwargs as sinks. A codebase that calls a tool, feeds the *raw*
+  result straight into a prompt (echofence's concern) and *separately*
+  saves that same raw result into long-term memory (agentmemorytaintgap's
+  concern) needs both tools — fixing one does not fix the other, since the
+  fix locations (the prompt-construction call vs. the memory-write call)
+  are different lines of code, and a codebase can have either problem
+  without the other (e.g. a raw tool result is fenced before hitting the
+  prompt, echofence clean, but the *same* raw value is separately persisted
+  into memory unsanitized, agentmemorytaintgap flags it — or vice versa: a
+  tool result is sanitized before being remembered, but a *different*,
+  unrelated external string is dropped unfenced into a prompt elsewhere).
+- **Timing/risk-shape distinction (the actual justification for a separate
+  tool, not just a separate sink list)**: echofence's risk window is one
+  request/response cycle — the poisoned content is gone once that call
+  returns. agentmemorytaintgap's risk window is the **lifetime of the
+  memory store** — a write that succeeds once can be read back and
+  re-injected into arbitrarily many future prompts, across sessions, without
+  the attacker doing anything further. This mirrors exactly the distinction
+  the 2026 memory-poisoning literature draws between single-session prompt
+  injection and memory poisoning.
+
+## Detection method (exact scope, stated honestly)
+
+This is **not** full data-flow / taint tracking. It is a pragmatic,
+heuristic, `ast`-only pass, described precisely so the false-positive and
+false-negative surface is knowable:
+
+1. **Per-function scope only.** Every `FunctionDef`/`AsyncFunctionDef` in the
+   module is analyzed independently. A memory write in one function can
+   never be traced to an assignment made in a different function, a class
+   `__init__`, or a module-level global — that is out of scope for v0.1.
+2. **Memory-write recognition is call-shape + naming based**, listed in full
+   in README.md: `save_context`, `chat_memory.add_message`/
+   `add_user_message`/`add_ai_message` (LangChain-shaped); `.add`/`.upsert`
+   on a variable whose name contains `memory`, `mem_store`, or `long_term`
+   (generic vector-store-as-memory — there is no single standard "agent
+   memory" API across frameworks the way there is for e.g. HTTP requests,
+   so this is a naming heuristic, not a type check); and free-function or
+   bound-method calls named `remember`, `store_memory`, or `save_memory`
+   (custom memory pattern).
+3. **Origin tracing is single-hop, within the writing function.** For the
+   value passed to a recognized memory-write call, the analyzer looks at:
+   - If it's a direct call expression (e.g. `search_tool.run(query)` used
+     inline) — classified immediately by call shape.
+   - If it's a bare variable name — the analyzer looks at how that name was
+     **last assigned** earlier in the same function (one hop back to that
+     assignment's right-hand side, not further). If that assignment's RHS
+     is itself another variable reference (not a call), the origin is
+     `unknown` rather than chased further — this is the "single-hop" line.
+   - If it's a bare function **parameter** with no prior assignment, the
+     analyzer checks only its **name** for a user-input signal
+     (`user_input`, `user_message`, `raw_input`, `user_query`, `message`) —
+     otherwise it's `unknown` (AT002), since a parameter's true origin is a
+     caller-scope question this tool does not follow.
+   - f-strings are inspected part-by-part; if any embedded expression is
+     untrusted, the whole f-string is untrusted; if all embedded parts are
+     provably trusted, it's trusted; otherwise unknown.
+4. **Untrusted-origin call shapes**: `.run(...)`/`.invoke(...)` on a
+   variable named with `tool` in it; a call to a module-level function
+   decorated with a recognizable `@tool` decorator (matched by decorator
+   name only, not by import source); `requests`/`httpx`/`aiohttp`
+   `.get/.post/.put/.patch/.delete(...)`; a call to a function literally
+   named `fetch`.
+5. **Trusted-origin call shapes** (short-circuit to safe, never flagged):
+   `.invoke(...)`/`.generate(...)`/`.predict(...)`/`.run(...)`/`__call__`
+   on a variable named with `llm`, `model`, or `chat` in it — the model's
+   own output.
+6. **Sanitization short-circuit**: if any call in the same function whose
+   name contains `sanitize`, `clean`, `validate`, `tag_source`, or
+   `mark_untrusted` is applied (as a positional first argument) to a
+   variable that also appears in the memory-write argument expression, the
+   finding for that write is suppressed entirely — no confidence scoring,
+   binary short-circuit, matching the sibling tools' style.
+7. Anything that can't be classified as trusted or untrusted by the rules
+   above is `unknown`, which becomes **AT002** (warning) rather than a
+   confident **AT001** (blocker) — the tool would rather under-claim
+   confidence than mislabel an ambiguous case as a hard blocker.
+
+### Known false negatives (by design, v0.1)
+
+- A memory-store variable not containing `memory`/`mem_store`/`long_term`
+  in its name (e.g. `db.add(tool_result)`) is invisible — the generic
+  vector-store pattern only fires on the naming heuristic.
+- A tool call through a wrapper/adapter that doesn't match `.run()`/
+  `.invoke()` on a `tool`-named variable, or isn't `@tool`-decorated by a
+  name this tool recognizes, is invisible.
+- Any origin resolved through more than one assignment hop, through a
+  class attribute, through a different function, or through a container
+  (list/dict) mutation is `unknown` at best, not a confident AT001.
+- A sanitize/tag function that doesn't match the recognized name
+  substrings is invisible — the write would be flagged as if unsanitized.
+
+### Known false positives (by design, v0.1)
+
+- A variable genuinely named `memory`/`db_memory`/etc. that isn't actually a
+  long-term memory store will still trigger the generic vector-store
+  pattern if `.add()`/`.upsert()` is called on it.
+- A function named `remember`/`store_memory`/etc. that does something
+  unrelated to agent memory (e.g. a cache) will still be treated as a
+  memory-write sink.
+- A `sanitize`-named function that doesn't actually neutralize untrusted
+  content (e.g. it only trims whitespace) still short-circuits the finding
+  — the tool trusts the function's name, not its behavior.
+
+## Verification performed for this release
+
+- `pip install -e '.[dev]'` in an isolated editable install of this
+  package only.
+- `pytest tests/ -v` — all unit and CLI tests passing (see `docs/USAGE.md`
+  test-run output).
+- Real CLI runs against all four `examples/` fixtures: an AT001 blocker
+  (tool output and HTTP fetch stored unsanitized), a clean sanitized
+  example, a clean example storing the LLM's own response, and an AT002
+  ambiguous-origin example — confirmed each produces the expected exit code
+  and finding shape.
+
+## License
+
+MIT © Jay Tank

agentmemorytaintgap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentmemorytaintgap-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.5
+Name: agentmemorytaintgap
+Version: 0.1.0
+Summary: Flags AI agent code that persists untrusted tool/external/user content into long-term memory with no sanitization or provenance marker (agent memory poisoning).
+Author: Jay
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,linter,llm-security,memory-poisoning,prompt-injection,static-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentmemorytaintgap
+
+**Catch untrusted content being written into an AI agent's long-term memory as if it were a trusted fact.**
+
+Prompt injection usually gets pictured as a single bad turn: a poisoned web
+page or tool result sneaks into one prompt, the model says something wrong
+once, and the blast radius ends there. Agent **memory** breaks that
+assumption. A growing class of agent frameworks let the agent persist
+content — a tool result, a summary, a "fact" — into a long-term memory store
+that gets read back and fed into *every future prompt* as if it were the
+agent's own trusted conclusion. If the content that gets written was actually
+attacker-controlled (a malicious tool response, a crafted user message, a
+poisoned web page), and nothing strips or tags it first, the poison survives
+for the lifetime of that memory store — this is the "agent memory poisoning"
+risk that's an increasingly-discussed, distinct branch of prompt injection in
+2026.
+
+`agentmemorytaintgap` reads your source with Python's `ast` module — no
+imports, no execution — and flags the memory-**write** call sites where that
+can happen:
+
+```
+$ agentmemorytaintgap agent/
+
+BLOCKER  AT001 agent/handler.py:3:4   Memory-write call stores content traced back to an untrusted origin (tool output / external fetch / raw user input) with no sanitization or provenance-tagging call in this function (agent memory poisoning risk).
+        agent_memory.save_context({"input": user_query}, {"output": tool_result})
+
+1 file(s) scanned · 1 blocker(s) · 0 warning(s)
+```
+
+Exit code `1` on a blocker, so it drops straight into pre-commit or CI.
+
+## What it flags
+
+| Rule | Severity | Fires when… |
+| :--- | :--- | :--- |
+| **AT001** | blocker | a memory-write call's stored value traces (single-hop, same function) back to a **provably untrusted** origin — tool output, an HTTP/fetch response, or a raw user-input parameter — with **no** sanitize/tag call on it anywhere in that function. |
+| **AT002** | warning | a memory-write call's stored value origin **could not be confidently traced** either way (a bare parameter with no naming signal, or a longer assignment chain). Lower confidence — worth a human glance, not a confident blocker. |
+
+The LLM's own generated response (e.g. `llm.invoke(...)`) is treated as
+trusted and is never flagged — the concern here is specifically *external*
+content being stored as if it were the agent's own conclusion.
+
+### Recognized memory-write shapes
+
+- LangChain-shaped: `.save_context(...)`, `.chat_memory.add_message(...)` /
+  `.add_user_message(...)` / `.add_ai_message(...)`.
+- Generic vector-store-as-memory: `.add(...)` / `.upsert(...)` called on a
+  variable whose name contains `memory`, `mem_store`, or `long_term` — there
+  is no single standard "agent memory" API the way there is for HTTP, so
+  this is a **naming heuristic**, documented honestly in `DETAILS.md`.
+- Custom memory helpers: a call to `remember(...)`, `store_memory(...)`, or
+  `save_memory(...)`, as a free function or bound method.
+
+### Recognized untrusted origins
+
+- A tool call: `.run(...)` / `.invoke(...)` on a variable named like `tool`,
+  or a call to a function decorated with a recognizable `@tool` decorator.
+- An external fetch: `requests`/`httpx`/`aiohttp` `.get/.post/...(...)`, or a
+  call to a function literally named `fetch`.
+- A raw user-input function parameter (named like `user_input`,
+  `user_message`, `raw_input`, `user_query`, or `message`).
+
+### Safe-marker short-circuit
+
+If a call whose name contains `sanitize`, `clean`, `validate`, `tag_source`,
+or `mark_untrusted` is applied to the value anywhere in the
+same function before the memory write, the finding does not fire — the
+short-circuit is deliberately generous, the same style as its sibling tools.
+
+## How it relates to echofence
+
+`echofence` and `agentmemorytaintgap` are both prompt-injection-adjacent AST
+linters, and they are **deliberately distinct, non-overlapping tools**:
+
+- **[`echofence`](https://github.com/jay-tank/echofence) — input side, single
+  turn.** Flags untrusted *external* content reaching a live LLM **prompt**
+  directly — the indirect variant of OWASP LLM01. The risk window is one
+  request/response cycle.
+- **`agentmemorytaintgap` — persistence side, every future turn.** Flags
+  untrusted content being **written into long-term memory** that will be
+  read back and replayed as trusted context across *every subsequent turn*,
+  potentially for the lifetime of the memory store. The artifact, the
+  timing, and the risk shape are different: a poisoned prompt affects one
+  answer; a poisoned memory write affects all future answers until someone
+  notices and purges the store.
+
+See `DETAILS.md` for the full, honest comparison — including why this is not
+just "echofence but for a different sink."
+
+## Install
+
+```bash
+pip install agentmemorytaintgap
+```
+
+## Usage
+
+```bash
+agentmemorytaintgap agent/                # scan a directory
+agentmemorytaintgap memory_handler.py      # scan a file
+agentmemorytaintgap agent/ --strict        # AT002 warnings fail the run too
+agentmemorytaintgap agent/ --json          # machine-readable output
+```
+
+### In CI
+
+```yaml
+- run: pip install agentmemorytaintgap
+- run: agentmemorytaintgap agent/ --strict
+```
+
+Exit codes: `0` clean · `1` a blocker (AT001), or any finding under
+`--strict` · `2` usage error.
+
+## Honest limitations
+
+`agentmemorytaintgap` is a **pragmatic, heuristic, single-hop,
+same-function-scope** analyzer — **not** full data-flow / taint analysis.
+See `DETAILS.md` for the complete breakdown, but concretely:
+
+- It only recognizes the memory-write shapes and naming conventions listed
+  above. A memory variable that doesn't contain `memory`/`mem_store`/
+  `long_term` in its name, or a tool call that doesn't match the recognized
+  `@tool`/`.run()`/`.invoke()` shapes, is invisible to v0.1.
+- Tracing is single-hop and scoped to one function. A value laundered
+  through a helper function it doesn't look inside of, or passed across
+  functions before being written to memory, will not be traced.
+- A sanitize/tag call anywhere in the function short-circuits the finding —
+  it trusts that the call actually does what its name implies; it does not
+  verify that.
+
+Treat it as a fast reviewer that catches the obvious, high-value cases on
+every PR, paired with human judgment for the rest.
+
+## License
+
+MIT © Jay Tank

agentmemorytaintgap-0.1.0/README.md

@@ -0,0 +1,138 @@
+# agentmemorytaintgap
+
+**Catch untrusted content being written into an AI agent's long-term memory as if it were a trusted fact.**
+
+Prompt injection usually gets pictured as a single bad turn: a poisoned web
+page or tool result sneaks into one prompt, the model says something wrong
+once, and the blast radius ends there. Agent **memory** breaks that
+assumption. A growing class of agent frameworks let the agent persist
+content — a tool result, a summary, a "fact" — into a long-term memory store
+that gets read back and fed into *every future prompt* as if it were the
+agent's own trusted conclusion. If the content that gets written was actually
+attacker-controlled (a malicious tool response, a crafted user message, a
+poisoned web page), and nothing strips or tags it first, the poison survives
+for the lifetime of that memory store — this is the "agent memory poisoning"
+risk that's an increasingly-discussed, distinct branch of prompt injection in
+2026.
+
+`agentmemorytaintgap` reads your source with Python's `ast` module — no
+imports, no execution — and flags the memory-**write** call sites where that
+can happen:
+
+```
+$ agentmemorytaintgap agent/
+
+BLOCKER  AT001 agent/handler.py:3:4   Memory-write call stores content traced back to an untrusted origin (tool output / external fetch / raw user input) with no sanitization or provenance-tagging call in this function (agent memory poisoning risk).
+        agent_memory.save_context({"input": user_query}, {"output": tool_result})
+
+1 file(s) scanned · 1 blocker(s) · 0 warning(s)
+```
+
+Exit code `1` on a blocker, so it drops straight into pre-commit or CI.
+
+## What it flags
+
+| Rule | Severity | Fires when… |
+| :--- | :--- | :--- |
+| **AT001** | blocker | a memory-write call's stored value traces (single-hop, same function) back to a **provably untrusted** origin — tool output, an HTTP/fetch response, or a raw user-input parameter — with **no** sanitize/tag call on it anywhere in that function. |
+| **AT002** | warning | a memory-write call's stored value origin **could not be confidently traced** either way (a bare parameter with no naming signal, or a longer assignment chain). Lower confidence — worth a human glance, not a confident blocker. |
+
+The LLM's own generated response (e.g. `llm.invoke(...)`) is treated as
+trusted and is never flagged — the concern here is specifically *external*
+content being stored as if it were the agent's own conclusion.
+
+### Recognized memory-write shapes
+
+- LangChain-shaped: `.save_context(...)`, `.chat_memory.add_message(...)` /
+  `.add_user_message(...)` / `.add_ai_message(...)`.
+- Generic vector-store-as-memory: `.add(...)` / `.upsert(...)` called on a
+  variable whose name contains `memory`, `mem_store`, or `long_term` — there
+  is no single standard "agent memory" API the way there is for HTTP, so
+  this is a **naming heuristic**, documented honestly in `DETAILS.md`.
+- Custom memory helpers: a call to `remember(...)`, `store_memory(...)`, or
+  `save_memory(...)`, as a free function or bound method.
+
+### Recognized untrusted origins
+
+- A tool call: `.run(...)` / `.invoke(...)` on a variable named like `tool`,
+  or a call to a function decorated with a recognizable `@tool` decorator.
+- An external fetch: `requests`/`httpx`/`aiohttp` `.get/.post/...(...)`, or a
+  call to a function literally named `fetch`.
+- A raw user-input function parameter (named like `user_input`,
+  `user_message`, `raw_input`, `user_query`, or `message`).
+
+### Safe-marker short-circuit
+
+If a call whose name contains `sanitize`, `clean`, `validate`, `tag_source`,
+or `mark_untrusted` is applied to the value anywhere in the
+same function before the memory write, the finding does not fire — the
+short-circuit is deliberately generous, the same style as its sibling tools.
+
+## How it relates to echofence
+
+`echofence` and `agentmemorytaintgap` are both prompt-injection-adjacent AST
+linters, and they are **deliberately distinct, non-overlapping tools**:
+
+- **[`echofence`](https://github.com/jay-tank/echofence) — input side, single
+  turn.** Flags untrusted *external* content reaching a live LLM **prompt**
+  directly — the indirect variant of OWASP LLM01. The risk window is one
+  request/response cycle.
+- **`agentmemorytaintgap` — persistence side, every future turn.** Flags
+  untrusted content being **written into long-term memory** that will be
+  read back and replayed as trusted context across *every subsequent turn*,
+  potentially for the lifetime of the memory store. The artifact, the
+  timing, and the risk shape are different: a poisoned prompt affects one
+  answer; a poisoned memory write affects all future answers until someone
+  notices and purges the store.
+
+See `DETAILS.md` for the full, honest comparison — including why this is not
+just "echofence but for a different sink."
+
+## Install
+
+```bash
+pip install agentmemorytaintgap
+```
+
+## Usage
+
+```bash
+agentmemorytaintgap agent/                # scan a directory
+agentmemorytaintgap memory_handler.py      # scan a file
+agentmemorytaintgap agent/ --strict        # AT002 warnings fail the run too
+agentmemorytaintgap agent/ --json          # machine-readable output
+```
+
+### In CI
+
+```yaml
+- run: pip install agentmemorytaintgap
+- run: agentmemorytaintgap agent/ --strict
+```
+
+Exit codes: `0` clean · `1` a blocker (AT001), or any finding under
+`--strict` · `2` usage error.
+
+## Honest limitations
+
+`agentmemorytaintgap` is a **pragmatic, heuristic, single-hop,
+same-function-scope** analyzer — **not** full data-flow / taint analysis.
+See `DETAILS.md` for the complete breakdown, but concretely:
+
+- It only recognizes the memory-write shapes and naming conventions listed
+  above. A memory variable that doesn't contain `memory`/`mem_store`/
+  `long_term` in its name, or a tool call that doesn't match the recognized
+  `@tool`/`.run()`/`.invoke()` shapes, is invisible to v0.1.
+- Tracing is single-hop and scoped to one function. A value laundered
+  through a helper function it doesn't look inside of, or passed across
+  functions before being written to memory, will not be traced.
+- A sanitize/tag call anywhere in the function short-circuits the finding —
+  it trusts that the call actually does what its name implies; it does not
+  verify that.
+
+Treat it as a fast reviewer that catches the obvious, high-value cases on
+every PR, paired with human judgment for the rest.
+
+## License
+
+MIT © Jay Tank

agentmemorytaintgap-0.1.0/docs/USAGE.md

@@ -0,0 +1,93 @@
+# Usage
+
+## Install
+
+```bash
+pip install agentmemorytaintgap
+```
+
+Or, for local development, from the package directory:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Scanning
+
+```bash
+agentmemorytaintgap path/to/agent_code.py
+agentmemorytaintgap path/to/agent_dir/
+agentmemorytaintgap file_a.py file_b.py dir_c/
+```
+
+Multiple files and directories can be passed together; directories are
+scanned recursively for `*.py` files.
+
+## Flags
+
+| Flag | Effect |
+| :--- | :--- |
+| `--json` | Emit a JSON payload (`findings`, `blockers`, `warnings`, `files_scanned`) instead of text. |
+| `--strict` | Also exit `1` when only AT002 warnings are present (default: AT002 alone exits `0`). |
+
+## Exit codes
+
+| Code | Meaning |
+| :--- | :--- |
+| `0` | No AT001 blockers (and, without `--strict`, no AT002-only failure). |
+| `1` | At least one AT001 blocker, or (with `--strict`) at least one AT002 warning. |
+| `2` | Usage error: no Python files found, or a file failed to parse (syntax error). |
+
+## Example: human-readable output
+
+```
+$ agentmemorytaintgap examples/unsafe_tool_output.py
+
+BLOCKER  AT001 examples/unsafe_tool_output.py:6:4   Memory-write call stores content traced back to an untrusted origin (tool output / external fetch / raw user input) with no sanitization or provenance-tagging call in this function (agent memory poisoning risk).
+        agent_memory.save_context({"input": user_query}, {"output": tool_result})
+BLOCKER  AT001 examples/unsafe_tool_output.py:12:4   Memory-write call stores content traced back to an untrusted origin (tool output / external fetch / raw user input) with no sanitization or provenance-tagging call in this function (agent memory poisoning risk).
+        memory_store.add(response.text)
+
+1 file(s) scanned · 2 blocker(s) · 0 warning(s)
+```
+
+## Example: JSON output
+
+```bash
+agentmemorytaintgap examples/unsafe_tool_output.py --json
+```
+
+```json
+{
+  "findings": [
+    {
+      "rule": "AT001",
+      "severity": "blocker",
+      "path": "examples/unsafe_tool_output.py",
+      "line": 6,
+      "col": 4,
+      "message": "Memory-write call stores content traced back to an untrusted origin (tool output / external fetch / raw user input) with no sanitization or provenance-tagging call in this function (agent memory poisoning risk).",
+      "source_line": "    agent_memory.save_context({\"input\": user_query}, {\"output\": tool_result})"
+    }
+  ],
+  "blockers": 2,
+  "warnings": 0,
+  "files_scanned": 1
+}
+```
+
+## In CI
+
+```yaml
+- name: Install
+  run: pip install agentmemorytaintgap
+- name: Check agent memory writes
+  run: agentmemorytaintgap agent/ --strict
+```
+
+## Running the test suite locally
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```

agentmemorytaintgap-0.1.0/examples/README.md

@@ -0,0 +1,16 @@
+# Examples
+
+- `unsafe_tool_output.py` — two AT001 blockers: raw tool/search output and a
+  raw HTTP fetch response stored directly into memory with no sanitization.
+- `clean_sanitized.py` — the same tool-output-into-memory pattern, but the
+  value passes through a `sanitize(...)` call first. No finding.
+- `clean_llm_response.py` — the LLM's own generated response (`llm.invoke(...)`)
+  stored into memory. Never flagged — this is the expected, safe pattern.
+- `ambiguous_origin.py` — an AT002 warning: the stored value is a bare
+  function parameter with no naming signal either way.
+
+Run against all of them:
+
+```bash
+agentmemorytaintgap examples/
+```

agentmemorytaintgap-0.1.0/examples/ambiguous_origin.py

@@ -0,0 +1,5 @@
+"""AT002: memory write whose argument origin can't be confidently traced."""
+
+
+def store_note(agent_memory, note):
+    agent_memory.save_context({"input": "note"}, {"output": note})

agentmemorytaintgap-0.1.0/examples/clean_llm_response.py

@@ -0,0 +1,7 @@
+"""Clean: the LLM's own generated response stored into memory - never flagged."""
+
+
+def handle_turn(agent_memory, llm, user_query):
+    reply = llm.invoke(user_query)
+    agent_memory.save_context({"input": user_query}, {"output": reply})
+    return reply