> 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
- Job: Build
- Product:
devin-brain - Packages:
devin-memory - Mode: mixed
- Foundation:
devin-internals-spec - Ecosystem:
awesome-devin· registry:devin-powerups
devin-memory
> 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.
Linux · Personal Windows · Corporate Windows
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/reflectover
.devin/memory/memories.jsonl) — append-only, no screening, no session
provenance.devin-memoryexports 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'ssessions.dbvia
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.dbthere 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.```bash
uv tool install 'devin-memory[mcp]'
or with `pipx` (alternative):```bash
pipx install 'devin-memory[mcp]'
For development:```bash
pip install -e ".[dev]"
pytest
## Usage```bash
# 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:```bash
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).
Client config:```json
{
"mcpServers": {
"devin-memory": {
"command": "devin-memory-mcp",
"args": ["--db", "/path/to/memory.db"]
}
}
}
The same stdio server registers in other MCP hosts:
Zed — context_servers in settings.json:```json
{
"context_servers": {
"devin-memory": {
"command": { "path": "devin-memory-mcp", "args": ["--db", "/path/to/memory.db"] }
}
}
}
**JetBrains** — Settings → Tools → AI Assistant → Model Context Protocol → Add:```json
{ "mcpServers": { "devin-memory": { "command": "devin-memory-mcp", "args": ["--db", "/path/to/memory.db"] } } }
Antigravity — ~/.gemini/config/mcp_config.json:```json
{ "mcpServers": { "devin-memory": { "command": "devin-memory-mcp", "args": ["--db", "/path/to/memory.db"] } } }
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 ` / `devin-memory approve
`). 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.```bash
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.
Once drafts sit in a skills tree, catalog-bridge registers them into the
devin-skill-catalog registry as
proposed entries — closing the write→gate→promote loop:```bash
scans .devin/skills/learned-*/SKILL.md and registers each as proposed
devin-learning catalog-bridge .devin/skills
then the catalog gates and promotes them (its own CLI):
devin-skill-catalog quarantine skill:learned-testing . --apply
devin-skill-catalog promote skill:learned-testing --apply
devin-skill-catalog activate skill:learned-testing --apply
The registry defaults to
`/.devin-ecosystem/skill-catalog.json` (resolved like
`devin-skill-catalog`; `DEVIN_CONFIG_DIR` wins) — override with
`--registry`. Entries carry metadata only (`kind`, `name`, `state`,
`sha256` of the SKILL.md, `origin` dir, empty `history`) — draft bodies are
never copied. The bridge is deterministic and idempotent: re-scanning an
unchanged draft changes nothing, an edited draft refreshes `sha256`, and
items the catalog already moved past `proposed` are reported as skipped and
left untouched. `--dry-run` prints the plan without writing. See
docs/skill-catalog-bridge.md for the
contract.
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).```bash
devin-learning weekly-report --sessions-db path/to/sessions.db --out ./docs/learning
Memory states
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
retainthat gives the opposite directive about the same
normalized subject as an existing active entry is stored alongside it with a
conflicts_withlink (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. extractscans one session'smessage_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 landproposed,
suspect onesquarantined.--auto-approveskips the review step.primeemits a compact# devin-memory: recalled context (heuristic)
block sized for a prompt hook. Entries scoped withretain --workspace
only prime inside that workspace; entries written under a different
machine profile never prime (the profile defaults tocorporate—
fail-closed).compactdeduplicates: non-retracted entries sharing exact
content+workspace+profilecollapse to one survivor — the
liveliest status wins (active>proposed>quarantined), ties keep
the oldest row. The other copies becomeretracted(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-groupkeep/retractedids,
truncated content sha256 — never content);--applyexecutes and runs
VACUUMon the file.quarantine --digestprints a deterministic audit fingerprint of the
lane: entry count, reason buckets by taxonomy family (free-form manual
reasons collapse tomanual:*), and a sha256 over the sorted per-entry
fingerprintssha256(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.
extractlifts
keyword-shaped sentences from one session into aproposedreview queue —
nothing becomes active withoutapprove(or--auto-approve). For a
richer lesson pipeline seedevin-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.
retainstores the
claimedsource_session_id/source_rowid;verifyaudits it against a
realsessions.dbafterwards. 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-memoryfor the CLI and optional MCP extra;devin-memory-mcpis 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 viaverify. - You want memory versioning —
supersede/retractkeep a history instead of silent edits. - You want to stay compatible:
exportwrites the Devin memory MCP'smemories.jsonlline 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
extractto read intent — it matches keyword signals and defaults toproposedprecisely 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.
Can devin-memory prove a memory came from a real session? Yes, via recorded provenance. retain --source-session --source-rowid stores the claimed origin, and devin-memory verify --sessions-db 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.
License
MIT — see LICENSE.
