DEV Community

Weber Gouin
Weber Gouin

Posted on

I gave Claude Code persistent memory and a common sense engine. Here's how.

#ai #opensource #python #claudecode

I'm a solo dev with 15 years in architecture and construction. Self-taught programmer. I use Claude Code every day for everything — Revit automation, full-stack projects, desktop scripting.

And every day, I hit the same wall:

Claude Code has no memory.

You spend 20 minutes correcting it — "don't force-push to main," "use this path, not that one," "my name is Weber, not Rick" — and then you close the terminal. Next session? Same mistakes. From scratch.

So I built Cadre — an open-source framework that bolts onto Claude Code and gives it persistent memory, structured execution, and what I call a "common sense engine."

This post is a technical deep-dive into how it works.

The Architecture (30-second version)

Cadre layers five systems on top of Claude Code:

┌─────────────────────────────────────────┐
│            Claude Code (CLI)            │
├─────────────────────────────────────────┤
│  Strong Agent Framework (5-phase)       │  ← structured execution
│  Common Sense Engine (kernel + seeds)   │  ← pre-action safety
│  Memory System (SQLite + FTS5 + MCP)    │  ← persistent recall
│  17 Sub-Agents + 22 Slash Commands      │  ← specialization
│  Hooks (correction capture, formatting) │  ← lifecycle automation
└─────────────────────────────────────────┘
Enter fullscreen mode Exit fullscreen mode

Everything installs to ~/.cadre-ai/ and ~/.claude/. No cloud. No daemon required. Pure local.

1. The Memory System

The core problem: Claude Code's context dies when the session ends. Cadre fixes this with a local MCP server backed by SQLite.

How it works

Every sub-agent can store and recall memories:

# Store a correction
memory_store_correction(
    what_claude_said="Used /opt/app as deploy path",
    what_was_wrong="Wrong path — should be /opt/app-v2",
    correct_approach="Always check the symlink target first",
    project="my-project"
)

# Recall before acting
memory_check_before_action(action="deploy to /opt/app")
# → Returns: "WARNING: correction found — use /opt/app-v2 instead"
Enter fullscreen mode Exit fullscreen mode

Storage backend

  • SQLite with WAL mode for concurrent writes
  • FTS5 full-text search for keyword recall
  • Optional sentence embeddings (BAAI/bge-small-en-v1.5 via fastembed) for semantic search
  • Engram cache — hash-based fast path so repeated queries don't hit the DB
  • Memory types: decision, fact, preference, correction, outcome, error
  • Project-scoped or global — corrections in one project don't bleed into another

The recall strategy is three-tiered

  1. Seed matching — check against 15 hardcoded universal corrections (in-memory, no DB hit)
  2. Keyword decomposition — strip stop words, build OR query, rank by match score
  3. Full-text fallback — LIKE %query% with importance/date ordering

This means even on first install, Cadre already knows 15 common mistakes. Then it learns your specific ones on top.

Session lifecycle

Every session starts with:

memory_smart_context(current_directory="/path/to/project")
Enter fullscreen mode Exit fullscreen mode

This pulls relevant memories, recent corrections, and project context — so Claude picks up where you left off.

Every session ends with a summary stored for next time:

memory_summarize_session(
    project="my-project",
    summary="Refactored auth module, fixed token refresh bug",
    key_outcomes=["auth.py simplified", "tests passing"],
    open_questions=["Should we migrate to JWT?"],
    next_steps=["Add refresh token rotation"]
)
Enter fullscreen mode Exit fullscreen mode

2. The Common Sense Engine

This is the piece I'm most proud of. It's a pre-action safety layer with three interlocking components.

The Decision Loop (kernel.md)

Injected into every agent's system prompt. Before every significant action, the agent runs through:

### 1. CLASSIFY the action
- Reversible? Can I undo this?
- Blast radius? Just me, or does this affect shared systems?
- Familiar? Have I done this exact thing before successfully?

### 2. CHECK experience
- Search correction memory for this action pattern
- If a past correction matches: APPLY it. Do not repeat the mistake.

### 3. SIMULATE one step ahead
"If I do this and it goes wrong, what happens?"
- Nothing bad - proceed
- Data loss or broken state - confirm with user first
Enter fullscreen mode Exit fullscreen mode

Eight judgment heuristics

Not rules - instincts:

  1. Read before write - never modify code you haven't read
  2. Verify before trust - screenshot after desktop automation, re-read after edits
  3. Small before big - incremental changes, not rewrites
  4. Ask before destroy - any destructive action gets confirmed
  5. Local before remote - test locally before pushing
  6. Specific before general - targeted fixes, not sweeping refactors
  7. Recent before stale - prefer fresh information
  8. Undo before redo - revert and retry rather than patch on top of broken

The Seed Database (seeds.json)

15 universal corrections loaded on first install. Every agent knows these before touching anything:

{
  "id": "git-002",
  "domain": "git",
  "what_went_wrong": "Committed secrets or .env files",
  "correct_approach": "Check staged files before committing. Never stage .env or sensitive files.",
  "detection": "git add, git commit with sensitive file patterns",
  "severity": "critical"
}
Enter fullscreen mode Exit fullscreen mode

Domains covered: filesystem, git, network, execution, scope, deployment, data, identity.

The Python API (sense.py)

For programmatic pre-action checks:

from sense import CommonSense

cs = CommonSense(project="my-project")

# Pre-action check
result = cs.before("git push --force origin main")
print(result.blocked)     # True
print(result.reason)      # "BLOCKED by [git-001]: Never force-push to shared branches."
print(result.confidence)  # 0.0

# Learning from mistakes
cs.learn(
    action="deployed to /opt/app",
    what_went_wrong="wrong path",
    correct_approach="check the symlink target first"
)

# Positive reinforcement
cs.succeeded("used SetProcessDPIAware() before SetWindowPos()")
Enter fullscreen mode Exit fullscreen mode

Confidence scoring

The before() method returns a confidence float (0.0-1.0) that degrades based on what it finds:

Finding Confidence cap
Critical correction match 0.0 (blocked)
High-severity correction 0.3
Unfamiliar action 0.6
Shared-state action (push, deploy, send) 0.7
No issues found 1.0

This lets agents make nuanced decisions - not just "allow/deny" but "proceed with caution."

3. The Strong Agent Framework

When Claude delegates to a sub-agent (via the Task tool), that agent doesn't "just wing it." It follows a mandatory 6-phase protocol:

Phase 0: Load Context 

memory_check_before_action -> memory_smart_recall -> absorb corrections
Enter fullscreen mode Exit fullscreen mode

Before touching anything, check what you know.

Phase 1: Orient

Parse the task. Rate your confidence:

  • High - proceed
  • Medium - proceed with extra thoroughness
  • Low - stop and report back. Don't guess.

Phase 2: Investigate

Read files in parallel. Grep patterns. Map dependencies. Never modify code you haven't read.

Phase 3: Execute

Small steps. Match existing code style. No unsolicited extras ("while I'm here, let me also refactor..."). Have a rollback plan.

Phase 4: Verify

Re-read changed files. Run tests. Grep for leftover TODOs/FIXMEs. For desktop automation: screenshot and visually verify.

Phase 5: Report

2-3 sentence summary + files changed + memory_store() with learnings.

The bail-out rules

These are explicit and non-negotiable:

  • Stuck for 3+ steps with no progress - stop
  • Confidence drops to LOW during execution - stop
  • Need a destructive action - stop and ask
  • Unfamiliar territory - stop and report

The anti-pattern this prevents: Claude spinning for 15 minutes on a task it doesn't understand, making things worse with each attempt.

4. The Agents

17 specialized agents, each defined as a markdown file with role, capabilities, workflow, rules, and output format.

Agent Domain
orchestrator Task decomposition - delegates, never does work itself
code-architect System design, produces Architecture Decision Records
code-simplifier Refactoring for clarity without behavior changes
python-engineer Python development
csharp-developer C#/.NET
fullstack-dev React/Node/Next.js
ml-engineer ML/data science (baseline first, then iterate)
devops-agent CI/CD, Docker, GitHub Actions
agent-builder Meta-agent - creates new agents using the same template
prompt-engineer Prompt design and optimization
test-runner Test execution
doc-scraper Documentation extraction
tech-scout Technology research and evaluation
market-analyst Market and competitive analysis
project-manager Planning and estimation
learning-agent Adaptive learning from outcomes
code-analyzer Deep code analysis for quality/performance

Creating your own agent

Agents are just markdown files with a structured format:

# My Custom Agent

You are a [domain] specialist...

## Capabilities
1. Thing it can do
2. Another thing

## Workflow
1. Understand the task
2. Investigate
3. Execute
4. Verify

## Rules
- Domain-specific guardrails
- What to never do

## Output Format
- How to structure the response
Enter fullscreen mode Exit fullscreen mode

Drop it in ~/.cadre-ai/agents/ and it's available via /delegate my-custom-agent.

5. The Hook System

Five hooks at five lifecycle points, handling things you shouldn't have to think about:

Pre-commit detection

Fires on every git commit:

patterns = [
    (r'hardcoded value pattern', "hardcoded value"),
    (r'sensitive key pattern', "sensitive key"),
    (r'cloud access pattern', "cloud value"),
]
Enter fullscreen mode Exit fullscreen mode

Blocks commits with .env or anything matching those patterns.

Automatic correction capture

This one's clever. detect_correction.py fires on every user message and scans for correction language:

patterns = [
    r"actually[,.]",
    r"you\s+forgot",
    r"that'?s\s+not\s+what\s+i\s+(asked|wanted|said)",
    r"no[,.]?\s+(I\s+)?(said|meant|want)",
]
Enter fullscreen mode Exit fullscreen mode

When it detects a correction, it tells Claude to call memory_store_correction() - so the mistake gets saved automatically without you having to say "remember this."

Auto-formatting

After any file edit, dispatches to the right formatter:

  • .py -> black
  • .js/.ts -> prettier
  • .cs -> dotnet format
  • .go -> gofmt
  • .rs -> rustfmt

Silently skips if the formatter isn't installed.

6. What it looks like in practice

Here's a real delegation flow:

Claude Code --- delegating to orchestrator
  |-- memory_smart_recall("project costs, spreadsheet")
  |   +-- Found: project_costs.xlsx on D:\Projects
  |-- launching sub-agent: excel-automation
  |   +-- Extracted 48 line items, $2.4M total
  |-- launching sub-agent: powerpoint-builder
  |   +-- save_as("Cost_Summary.pptx")
  |-- memory_store("cost summary pipeline created")
  +-- voice: "Done. 3-slide deck saved."
Task complete in 34 seconds
Enter fullscreen mode Exit fullscreen mode

And a correction getting captured:

You:    "No, use /opt/app-v2, not /opt/app"
Hook:   [detect_correction] -> correction language detected
Claude: memory_store_correction(
          what_claude_said="deployed to /opt/app",
          what_was_wrong="wrong path",
          correct_approach="use /opt/app-v2"
        )
Enter fullscreen mode Exit fullscreen mode

Next session, when Claude tries to deploy:

memory_check_before_action("deploy to /opt/app")
-> "WARNING: correction found - use /opt/app-v2"
Enter fullscreen mode Exit fullscreen mode

It doesn't make the same mistake twice.

Install 

git clone https://github.com/WeberG619/cadre-ai.git
cd cadre-ai
./install.sh
Enter fullscreen mode Exit fullscreen mode

Interactive installer, three tiers:

Tier What you get
Minimal Framework + agents + commands
Developer + memory MCP + voice + git hooks
Power User + Excel/browser automation + system bridge

Works on WSL, macOS, and Linux. The installer detects your platform and only offers components that work on it.

What I want from you

This is a real tool I use daily. It works for my workflow. But I don't know if it works for yours.

I want honest feedback:

  1. Did the install work? What broke?
  2. What's confusing about the architecture?
  3. What's missing that you expected?
  4. Would you actually use this?

There's a structured feedback form: GitHub Feedback Form

Or just leave a comment here. Roast it, praise it, whatever - I just want to know what real Claude Code users think.

GitHub: github.com/WeberG619/cadre-ai

Built with Claude Code, obviously.

Top comments (0)