io.github.Icaro0310/devin-memory

devin-memory

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/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

1. 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.
2. No-Devin: without sessions.db there is no session provenance to audit — the extra disappears.
3. 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 and pipx are required. Windows (PowerShell): install pipx with py -m pip install --user pipx, run py -m pipx ensurepath, then reopen the terminal. Linux (Debian/Ubuntu): run sudo apt install pipx python3-venv and pipx ensurepath; reopen the terminal. Other Linux distributions should install pipx using their package manager.

pipx install "devin-memory==0.3.0"

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

# Keyword-ranked recall — returns active entries only
devin-memory recall "ci status" [--json] [--limit 5] [--tags a,b]

# 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

# 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"
devin-memory retract <id>
devin-memory list [--status active|proposed|quarantined|retracted] [--json]

# 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==0.3.1"

Client config:

{
  "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. Every tool returns structured data or a {"error", "detail"} object — nothing raises through the transport. DEVIN_MEMORY_DB works as an alternative to --db.

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.

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.

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).

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.

License

MIT — see LICENSE.