Part of the DEVIN ecosystem
Track: Build · Nature: product
For: AI engineers, Developers, Data Scientists
Interface: CLI / Python library / MCP server / Service
Path: AI engineers · step 3/3 — after devin-orchestrator
Where this fits
Anti-poisoning memory for agents: provenance, conflicts, quarantine gate.
Renamed (Oct 2026): this repository moved from Icaro0310/devin-memory
to Icaro0310/devin-brain — the PyPI package, CLI commands and MCP server
name stay devin-memory; stars, issues and history are preserved by the
GitHub redirect.
Unofficial community project. Not affiliated with, endorsed by, or
sponsored by Cognition AI. "Devin" is a trademark of Cognition AI.
Part of the awesome-devin ecosystem: the curated hub for the devin-* tools.
An anti-poisoning memory store for Devin: durable facts with provenance,
versioning, and a quarantine gate — so agent memory can't be silently
corrupted by a bad session or injected content.
The problem
Agent memory is a poisoning vector. Any tool that persists "facts" between
sessions can be corrupted by a single bad session — an injected instruction
or a pasted secret becomes a trusted belief in every future session, with no
review step and no way to answer "where did this come from?".
Prior art
The Devin memory MCP (retain/recall/reflect over
.devin/memory/memories.jsonl) — append-only, no screening, no session
provenance. devin-memory exports to that exact line shape.
MemGPT / LangChain memory — persistence layers that optimize for
recall, not for auditing or distrusting what was stored.
devin-memory adapts the memory-store idea; it adds the parts those tools
don't have: a quarantine gate and provenance back to real session rows.
What makes it Devin-native
Side-by-side: every entry can carry source_session_id +
source_rowid, auditable against Devin's sessions.db via
devin-internals' read-only store — the memory MCP cannot verify that a
claimed source session (or a specific message row) ever existed. The
quarantine gate also screens every write for secret and injection shapes.
No-Devin: without sessions.db there is no session provenance to
audit — the extra disappears.
One sentence:it's a memory store that remembers where each memory
came from — and quarantines suspicious ones until a human releases them.
Install
Python ≥ 3.10 required; install with uv (recommended) or pipx.
uv tool install 'devin-memory[mcp]'
or with pipx (alternative):
pipx install 'devin-memory[mcp]'
For development:
pip install -e ".[dev]"
pytest
Usage
# Store a fact (screened on write; suspect content lands in quarantine)
devin-memory retain "CI is green on Windows + Linux" --tags ci,status
devin-memory retain "..." --source-session <session-id> --source-rowid <n>
devin-memory retain "..." --workspace /path/to/project # scope to a workspace
devin-memory retain "..." --expires-at 2026-12-31T00:00:00Z # TTL: drops
# out of recall/prime after this instant
# Keyword-ranked recall — returns active, unexpired entries only;
# scores are weighted by recency decay so fresh memories outrank stale ones
devin-memory recall "ci status" [--json] [--limit 5] [--tags a,b]
devin-memory recall "ci status" --include-expired # also surface expired
# Quarantine lane: list, mark an existing entry, or release one
devin-memory quarantine # list with reasons
devin-memory quarantine <id> [--reason manual:x] # mark entry as quarantined
devin-memory quarantine --release <id> # human override -> active
devin-memory quarantine --digest [--json] # audit hash (read-only)
# Contradictions: a conflicting retain is linked, not overwritten
devin-memory conflicts [--json] # (newer, older) pairs; resolve with
# supersede / retract / quarantine <id>
# Mine a session for durable knowledge -> proposed entries (inactive
# until reviewed); extraction is heuristic — see "Limitations"
devin-memory extract <session-id> --sessions-db path/to/sessions.db
devin-memory extract --latest --sessions-db path/to/sessions.db [--auto-approve]
devin-memory list --status proposed # review queue
devin-memory approve <id> # proposed -> active
# Context block for a UserPromptSubmit hook — active entries only,
# filtered by workspace + machine profile, bounded by ~4 chars/token
devin-memory prime [--workspace PATH] [--max-tokens N]
# Versioning and housekeeping
devin-memory supersede <id> "corrected fact" [--expires-at <iso>]
# default: inherit old expiry
devin-memory retract <id>
devin-memory list [--status active|proposed|quarantined|retracted] [--json]
devin-memory compact [--json] # dedup report (dry-run)
devin-memory compact --apply # retract copies + vacuum the file
# Audit an entry's provenance against a real sessions.db (read-only)
devin-memory verify <id> --sessions-db path/to/sessions.db
# Export active memories to a memory-MCP-compatible JSONL
devin-memory export --out memories.jsonl
MCP server
devin-memory is also a real MCP server (stdio) — the same retain/recall
pipeline with the quarantine gate on every write, callable from Devin,
Claude Desktop, Cursor or any MCP client:
pipx install "devin-memory-mcp"
The devin-memory-mcp console script also ships inside the base
devin-memory dist, so a bare uv tool install devin-memory (no extra)
leaves a script that exits with error: The MCP server needs the 'mcp' extra — recovery steps live in the Troubleshooting section of each
platform guide (Linux,
Personal Windows,
Corporate Windows).
Tools: retain, recall, screen (dry-run the gate, no write), list,
retract, supersede, quarantine, release, approve, conflicts,
prime, verify, extract, compact, quarantine_digest. The release
and approve promotion overrides are only registered when the server runs
with DEVIN_MEMORY_MCP_PROMOTE=1 — otherwise promotion stays human-only via
the CLI (devin-memory quarantine --release <id> / devin-memory approve <id>). The same flag gates extract's auto_approve parameter, which is
forced off without the opt-in so an AI client cannot skip the review step.
Every tool returns structured data or a {"error", "detail"}
object — nothing raises through the transport. DEVIN_MEMORY_DB works as an
alternative to --db.
VS Code:adapters/vscode/ ships an extension that registers this
server with the editor's built-in MCP support (server definition provider,
VS Code ≥1.102) — launch command, optional DEVIN_MEMORY_DB and workspace
cwd are declared there; the promotion opt-in is pinned off so the
editor-facing server keeps its non-promoting surface.
adapters/ is a self-contained Devin plugin root
(adapters/.devin-plugin/plugin.json + adapters/skills/devin-brain/SKILL.md),
installed with
devin plugins install Icaro0310/devin-brain#adapters — it ships in the
repo, not inside the wheel. The manifest launches the server through
uvx --from 'devin-memory[mcp]' devin-memory-mcp; the promotion
opt-in (DEVIN_MEMORY_MCP_PROMOTE) is never set, so the plugin-facing
server keeps its non-promoting surface. To run against a checkout
instead of PyPI, point a local manifest copy at
uvx --from '.[mcp]' devin-memory-mcp.
Learn from sessions with devin-learning
This companion CLI extracts candidate lessons from a sessions.db and writes
reviewable skill drafts. It does not install drafts into a workspace by default.
devin-learning extract --sessions-db path/to/sessions.db --out ./learning-drafts
devin-learning review --out ./learning-drafts
# After reviewing drafts, explicitly allow output to a live skill directory:
devin-learning extract --sessions-db path/to/sessions.db --out .devin/skills --apply
review is a dry-run unless --apply is given; review --apply moves rejected
drafts under _rejected/. The extractor reads session contents, so keep its
output private until reviewed.
For a shareable summary there is weekly-report — the public surface of the
loop. It emits weekly-YYYY-Www.md with aggregate counts only (lessons by
theme, promoted learned-* skills, quarantine-pending buckets): no session
text, ids or paths, so the file is safe to commit. It resumes from the
devin-learning-weekly cursor, falling back to the last --days (default 7).
active · proposed (extracted, awaiting approve) · quarantined
(screened or manually flagged, awaiting release) · retracted (withdrawn or
superseded). Only active entries surface in recall/prime/export —
quarantined content is never printed and never recalled.
An active entry can also carry expires_at (ISO-8601, set at retain/
supersede or changed via set_expires_at): once the instant passes the
entry is excluded from recall/prime — excluded, not deleted, so it stays
visible in list/export --all for audit (recall --include-expired
opts out). Entries without expires_at never expire. Separately, recall
applies an exponential recency decay to keyword scores (half-life 30 days,
ops.RECALL_DECAY_HALF_LIFE_DAYS, tunable per call via half_life_days) —
fresher memories win close calls while clearly stronger stale hits still
rank first.
Conflicts, extraction and prime (heuristics)
Conflicts — a retain that gives the opposite directive about the same
normalized subject as an existing active entry is stored alongside it with a
conflicts_with link (devin-memory conflicts). The heuristic compares a
stop-word-stripped "subject key" plus affirmative/prohibitive polarity — it
deliberately misses reworded contradictions rather than mislinking facts.
extract scans one session's message_nodes (read-only via
devin-internals) for durable-knowledge signals — user corrections
("na verdade", "actually", "the right way"), preferences ("always", "never",
"sempre", "nunca"), discovered commands (backticked known tools) and paths.
Candidates are screened like any write: clean ones land proposed,
suspect ones quarantined. --auto-approve skips the review step.
prime emits a compact # devin-memory: recalled context (heuristic)
block sized for a prompt hook. Entries scoped with retain --workspace
only prime inside that workspace; entries written under a different
machine profile never prime (the profile defaults to corporate —
fail-closed).
compact deduplicates: non-retracted entries sharing exact
content + workspace + profile collapse to one survivor — the
liveliest status wins (active > proposed > quarantined), ties keep
the oldest row. The other copies become retracted (never deleted —
history and reasons stay auditable) and the survivor inherits the union
of tags from copies sharing its status — quarantined or proposed tags
never bleed into an active entry. Default is a
dry-run report (live entries N→M, per-group keep/retracted ids,
truncated content sha256 — never content); --apply executes and runs
VACUUM on the file.
quarantine --digest prints a deterministic audit fingerprint of the
lane: entry count, reason buckets by taxonomy family (free-form manual
reasons collapse to manual:*), and a sha256 over the sorted per-entry
fingerprints sha256(content)+sorted(reasons). Keyed on content, not row
ids — two stores holding the same quarantined facts digest identically,
and any membership or reason change moves it. Always read-only.
The store is ./memory.db by default — override with --db or
DEVIN_MEMORY_DB. It is the only store this tool writes to; Devin's
sessions.db, acp-messages/*.db and state.vscdb are only ever read.
Works with Devin alone (Devin-only mode)
devin-memory keeps a local memory store (JSONL) with provenance tracking and
a quarantine lane — no external memory service, no network calls. Both console
scripts (devin-memory and devin-learning) run on your machine only.
Honest caveat: write-time screening is a heuristic, not a guarantee — suspect
entries land in quarantine for human review, so keep that habit.
Platform support
The memory store uses an explicit local SQLite path and the session database is
provided with --sessions-db; no platform-specific path is assumed. Windows
and Linux are supported and covered by CI.
Limitations
Extraction is heuristic, and proposed by default.extract lifts
keyword-shaped sentences from one session into a proposed review queue —
nothing becomes active without approve (or --auto-approve). For a
richer lesson pipeline see devin-learning.
The screen is a filter, not a guarantee. Pattern-based secret detection
and injection heuristics have both false positives (→ quarantine, one
command to release) and false negatives. Run dedicated scanners
(gitleaks, devin-redact) too — this complements them.
Recall ranking is keyword-based, deterministic and documented — no
embeddings or semantic search in M1.
Provenance is recorded, not self-verifying.retain stores the
claimed source_session_id/source_rowid; verify audits it against a
real sessions.db afterwards. A bad actor can claim fake provenance —
the point is that it is checkable.
Quarantined supersessions still retire the old version. If the
replacement quarantines, review the queue (quarantine --release).
PyPI distributions:devin-memory for the CLI and optional MCP extra; devin-memory-mcp is the standalone MCP-registry package.
When to use this
You persist agent memory between sessions and want it distrust-by-default: every write screened, suspect entries quarantined for human release.
You need to answer "where did this memory come from?" — entries carry source_session_id/source_rowid, auditable via verify.
You want memory versioning — supersede/retract keep a history instead of silent edits.
You want to stay compatible: export writes the Devin memory MCP's memories.jsonl line shape.
When NOT to use this
You need semantic recall — ranking is keyword-based, no embeddings.
You expect the screen to catch everything — it is a heuristic filter; run dedicated scanners (gitleaks, devin-redact) alongside.
You expect extract to read intent — it matches keyword signals and defaults to proposed precisely because heuristics err.
FAQ
How do I stop agent memory from being poisoned by a bad session? Use devin-memory retain instead of appending to a raw store. Every write is screened for secret and injection shapes — suspect entries land in quarantine and only become active after a human runs quarantine --release <id>.
Can devin-memory prove a memory came from a real session? Yes, via recorded provenance. retain --source-session <id> --source-rowid <n> stores the claimed origin, and devin-memory verify <id> --sessions-db <path> audits it read-only against Devin's actual sessions.db — a fabricated source is checkable, not silently trusted.
Does devin-memory replace the Devin memory MCP? It complements it. The MCP is append-only with no screening; devin-memory adds quarantine, provenance and versioning, and devin-memory export --out memories.jsonl produces the exact line shape the MCP reads.
