> your AI agent picks dependencies from memory; give it dated facts — try starlog.dev ↗ vet your agent's deps ↗ vibe-coding is fine. vibe-importing isn’t. — try starlog.dev ↗ vibe-importing isn’t fine ↗ your agent has never seen your private packages — try starlog.dev ↗ facts for private packages ↗ a linter for the dependencies your AI agent picks — try starlog.dev ↗ a linter for agent deps ↗ whois is redacted, cdns mask the rest — get the real operator — try whoisgeni.us ↗ who really runs that domain ↗ domain attribution that shows its work — full evidence chain — try whoisgeni.us ↗ domain intel w/ evidence ↗

← Back to Articles

Building Agent Memory Hierarchies: Why Your AI Coding Assistant Keeps Making The Same Mistakes

[ View on GitHub ]

Building Agent Memory Hierarchies: Why Your AI Coding Assistant Keeps Making The Same Mistakes

Hook

Your AI coding assistant has a 200k token context window but keeps suggesting the same architectural anti-pattern it violated last week. The problem isn't memory capacity—it's memory hygiene.

Context

The current generation of AI coding assistants—Claude Code, Cursor, Continue.dev—suffer from a peculiar amnesia. They can 'remember' entire codebases through RAG indexing and hold 200k+ tokens in working memory, yet they repeatedly violate project conventions, ignore previously-learned lessons, and accumulate contradictory instructions over time. The root cause isn't the LLM itself but how we structure agent context.

Most teams start with a simple CLAUDE.md or .cursorrules file containing project guidelines. Over weeks, this file metastasizes: someone adds a note about the authentication flow, another entry about database migration patterns, a reminder not to use deprecated APIs. Six months in, you have 8,000 tokens of conflicting, outdated instructions that the agent treats with equal weight. There's no promotion mechanism for repeated lessons, no archival process for obsolete rules, and no distinction between 'always load this' versus 'retrieve when relevant.' q-agent-harness treats this as what it actually is: a memory hierarchy problem that software engineering solved decades ago with CPU caches.

Technical Insight

The core architecture implements four memory tiers that mirror how computer systems manage data locality. Hot memory (memory/hot/) contains always-loaded rules under 2,000 tokens—critical constraints like 'never commit API keys' or 'all database queries use parameterized statements.' Episodic memory (memory/episodic/) logs individual task sessions with structured entries. Semantic memory (memory/semantic/) holds reference documentation and context that's retrieved on-demand. Procedural memory (memory/procedural/) contains proven workflows extracted from repeated episodic patterns.

Here's what an episodic entry looks like:

## 2024-01-15: Authentication bypass in admin panel

**Task**: Add role-based access control to dashboard
**Outcome**: Failed - accidentally exposed admin endpoints
**What worked**: Using decorator pattern for permission checks
**What failed**: Forgot to apply decorators to new blueprint routes
**Lesson**: All Flask blueprints must pass through register_blueprint_with_auth() wrapper

The compaction workflow analyzes these episodic logs to identify recurring failures. If the authentication decorator mistake appears three times across different tasks, the scripts/compact tool (which uses the Claude CLI to analyze token budgets and pattern frequency) proposes promoting it to procedural memory:

# scripts/compact analyzes episodic/ and suggests promotions
$ ./scripts/compact

Analyzing 47 episodic entries...
Pattern detected (3 occurrences): Flask blueprint registration without auth wrapper

Proposed procedural workflow:
---
When adding new Flask blueprints:
1. Define blueprint: bp = Blueprint('name', __name__)
2. Add routes with @bp.route() decorators
3. Register via: register_blueprint_with_auth(app, bp, required_role='user')
4. Verify in memory/hot/rules.md that blueprint appears in auth checklist
---

Promote to memory/procedural/flask-blueprints.md? [y/N]

This creates an actual learning loop. Repeated mistakes don't just accumulate in logs—they transform into reusable workflows. If a procedural workflow proves universally critical (like the blueprint auth wrapper), human review can promote it further to hot memory as an always-loaded rule.

The memory tier separation enables something profound: structured forgetting. When your team migrates from Flask to FastAPI, you can archive memory/procedural/flask-blueprints.md without losing memory/procedural/api-versioning.md or memory/hot/security-rules.md. Most agent frameworks only support append-only context, making technical debt in prompts as inevitable as technical debt in code.

The task-setups.md pattern explicitly models context configuration as a function of task risk. Debugging production issues loads a minimal context with read-only permissions and exhaustive verification loops. Exploratory research work loads broader semantic memory with relaxed verification. Here's the debugging profile:

## Setup: Production Debugging

**Hot Memory**: security-rules.md, incident-protocols.md
**Procedural**: debugging-workflows.md only
**Semantic**: None (reduce distraction)
**Tools**: Read-only database access, log aggregation
**Verification**: Four-loop (type → integration → staging deploy → manual approval)

This harness-as-configuration approach means the same agent behaves differently based on explicitly declared context boundaries rather than hoping the LLM infers appropriate caution from chat history. The VERIFICATION.md four-loop model (type checking, integration tests, UI validation, product review) creates graduated approval gates instead of binary 'autonomous' versus 'supervised' modes.

Gotcha

The entire system depends on manual curation discipline that degrades without friction-reducing tooling. Writing structured episodic entries after every coding session is organizational overhead—like insisting developers write perfect commit messages without pre-commit hooks to enforce format. Teams that adopt this will see initial enthusiasm collapse after two weeks unless someone builds IDE integration that makes episodic logging one-click.

There's zero runtime enforcement of the architecture you document. The docs/architecture-boundaries.md file might declare 'frontend code cannot directly import database models,' but unless your underlying agent platform (Claude Code, Cursor) supports custom validators, nothing prevents the agent from violating this. You're trusting markdown documentation to constrain behavior, which works only if the agent is prompted to read and respect those docs every invocation. The compaction scripts also won't prevent someone from bloating hot memory to 10,000 tokens, defeating the whole cache-locality premise. This is infrastructure-as-documentation, not infrastructure-as-code—it shapes behavior through convention rather than enforcement.

Verdict

Use if: You're running long-lived agent-assisted development where the same human-agent pair works on a codebase for months, you've already experienced the 'agent makes the same architectural mistake twice' problem, your team can commit to disciplined episodic logging (or will build tooling to automate it), and you need structured context management for codebases where a single 8k-token instruction file has become unmaintainable. This is harness engineering for human-in-the-loop workflows where context drift is measurably costing velocity. Skip if: You're doing one-off agent tasks, haven't yet hit the context bloat problem (your .cursorrules is still under 2k tokens), can't maintain logging discipline, or need autonomous agent loops without human compaction review. For simpler projects, a well-curated single instruction file beats this four-tier hierarchy. For programmatic context injection with actual runtime enforcement, build custom MCP servers instead of curating markdown.