SpecMem Logo

SpecMem

Inspiration

Every developer using AI coding agents knows the pain: you're drowning in markdown files.

CLAUDE.md, AGENTS.md, .cursorrules, requirements.md, design.md, tasks.md... the list grows with every feature. These specifications represent hours of careful thought, architectural decisions, and acceptance criteria. But what happens to them after the feature ships?

They rot. They're forgotten. They become digital dust.

Meanwhile, your AI coding agent starts fresh every session, blissfully unaware of the specs you painstakingly wrote yesterday. It makes the same mistakes. It ignores your constraints. It has amnesia.

We watched this happen across teams using Kiro, Claude Code, Cursor, and other AI coding tools. The industry had created powerful agents that could write code, but nobody had solved the memory problem. Nobody had figured out how to turn specification chaos into Agent Experience.

We also noticed a painful divide: Spec-Driven Development felt like waterfall (verbose docs, bureaucratic gates, spec rot), while vibe coding meant chaos (agents forget everything, repeat mistakes, no constraints). There had to be a middle ground.

That's what inspired SpecMem: Pragmatic SDD that strikes the perfect balance between structure and flexibility.

What it does

SpecMem is the first-ever Agent Experience (AgentEx) platform: a unified, embeddable cognitive memory layer for AI coding agents.

Think of it as DevEx, but for AI agents. Just like we optimize developer experience for humans, SpecMem optimizes the experience for coding agents by giving them:

Capability	Description
Persistent Memory	Specs become searchable knowledge that survives sessions
Semantic Search	Agents query specs using natural language
Impact Awareness	Know exactly which specs relate to which code changes
Living Documentation	Specs that stay in sync, detect drift, and validate themselves
Agent Portability	Switch from Kiro → Claude Code → Cursor without losing context
Executable Specs	Run in GitHub Actions with coverage thresholds and PR comments

The Killer Feature: Swap agents without losing your project knowledge. Every coding agent uses its own proprietary format (Claude uses CLAUDE.md, Cursor uses .cursorrules, Kiro uses .kiro/specs/). SpecMem breaks this lock-in with agent-agnostic adapters that read ANY format and output to ANY agent.

Key Features:

🔌 10+ Framework Adapters: Kiro, SpecKit, Tessl, Claude Code, Cursor, Codex, Factory, Warp, Gemini CLI
🧠 Cognitive Memory: Vector-based semantic search with pinned memory for critical specs
📊 SpecImpact Graph: Bidirectional relationships between specs ↔ code ↔ tests
⏱️ SpecDiff Timeline: Track spec evolution, detect drift, find contradictions
✅ SpecValidator: 6 quality rules for specification health
📈 Spec Coverage: Map acceptance criteria to tests, identify gaps
🎯 Selective Testing: Run only tests affected by code changes
💚 Health Scores: Project health grades (A-F) with improvement suggestions
🌐 Web UI: Interactive dashboard with live sync and WebSocket updates
🤖 GitHub Action: CI integration with PR comments and configurable thresholds
🔗 MCP Server: Native Kiro Powers integration via Model Context Protocol
📤 Static Dashboard: Export specs to GitHub Pages
🔄 Spec Lifecycle: Prune stale specs, generate from code, compress verbose specs
☁️ Cloud Embeddings: OpenAI, Google, Together AI support

How we built it

SpecMem was built during Kiroween 2025 with a focus on real-world developer pain points.

Architecture:

SpecIR (Intermediate Representation): Canonical format that normalizes all specification formats into typed blocks (requirement, design, task, decision, knowledge)
Pluggable Vector Backends: LanceDB (default), ChromaDB, Qdrant, or our lightweight AgentVectorDB
Multi-Framework Adapters: Each adapter maps its format to SpecIR without losing information
SpecImpact Graph: NetworkX-based bidirectional graph connecting specs, code files, and tests
MCP Server: Full Model Context Protocol implementation for Kiro integration

The Stack:

Python 3.11+ with full type hints
Typer for CLI (30+ commands)
Pydantic for data models and validation
LanceDB as default vector store
FastAPI + WebSockets for Web UI
Hypothesis for property-based testing
GitHub Actions for CI/CD

Key Technical Decisions:

Local-First: Works offline with local embeddings, cloud optional
Agent-Agnostic: No vendor lock-in, works with any coding agent
MCP Native: Full Model Context Protocol support for seamless Kiro integration
Living Documentation: File watcher auto-reindexes on spec changes
Executable Specs: GitHub Action makes specs enforceable, not just documentation

Challenges we ran into

1. The Adapter Explosion Every coding agent has its own spec format. We started with Kiro, then added Claude, then Cursor... suddenly we had 10 adapters to maintain. The challenge was creating a unified SpecIR that could represent all formats without losing information.

Solution: We designed SpecIR to be flexible with typed blocks and extensible metadata. Each adapter maps to this canonical format while preserving source-specific details.

2. Semantic Search Quality Early versions returned irrelevant specs. A query for "authentication" would return specs about "authorization" or completely unrelated features.

Solution: We added pinned memory for critical specs (constraints, architecture rules) that always appear in results. We also implemented relevance scoring that considers both semantic similarity and structural importance.

3. The "Spec Rot" Problem Specs drift from reality. Requirements change but specs don't. We needed to detect this automatically without manual intervention.

Solution: SpecDiff Timeline tracks spec evolution over time. SpecValidator detects contradictions across specs. Health scores identify orphaned and stale specs that need attention.

4. Context Window Limits Agents have limited context windows. Dumping all specs would overflow them and waste tokens.

Solution: SpecImpact Graph enables selective context. When you change auth/service.py, SpecMem returns only the specs related to authentication, not your entire project. Token-aware streaming optimizes context delivery.

5. Adoption Barrier SDD requires discipline. Not everyone writes specs. How do you onboard teams that have code but no specifications?

Solution: We added specmem generate to bootstrap specs from existing code. Teams can adopt gradually, starting with auto-generated specs and refining over time.

Accomplishments that we're proud of

🏆 First-ever Agent Experience (AgentEx) platform for AI coding agents

⚖️ Struck the perfect balance between Spec-Driven Development and vibe coding with Pragmatic SDD

🔓 Broke vendor lock-in: Agent-agnostic adapters let you switch between Kiro, Claude Code, Cursor, and others without losing context

📜 Living Documentation: Executable specifications that stay in sync, validate themselves, and run in CI

🤖 GitHub Action Ready: Specs aren't just docs, they're enforceable with coverage thresholds and PR comments

🔌 10+ Framework Adapters: Comprehensive support for the entire AI coding agent ecosystem

🧠 4 Vector Backends: LanceDB, ChromaDB, Qdrant, AgentVectorDB for any deployment scenario

🔗 MCP Native: Full Model Context Protocol support for seamless Kiro Powers integration

📊 Complete Spec Lifecycle: From generation to validation to pruning, we handle the entire lifecycle

🌐 Beautiful Web UI: Interactive dashboard with live sync, filtering, and real-time updates

What we learned

1. Memory is the Missing Layer AI coding agents are powerful but forgetful. The industry focused on making agents smarter, but nobody built the memory infrastructure. SpecMem fills this critical gap.

2. Portability Matters More Than Features Developers hate lock-in. The ability to switch agents without losing context resonated more strongly than any individual feature. Freedom to choose your tools is paramount.

3. Living > Static Static documentation dies. Living documentation that auto-updates, validates itself, and detects drift is what teams actually need. Specs must evolve with the codebase.

4. CI Integration is Essential Specs that aren't enforced get ignored. Running SpecMem in GitHub Actions with coverage thresholds makes specs executable, not just documentation. Enforcement drives adoption.

5. Pragmatism Wins Pure SDD is too rigid. Pure vibe coding is too chaotic. The sweet spot is pragmatic SDD with intelligent tooling that helps without getting in the way.

6. Agents Need Context, Not Everything Dumping all specs into an agent's context is wasteful and counterproductive. Selective, impact-aware context delivery is the key to effective agent memory.

What's next for SpecMem

Short Term:

📦 More Adapters: Windsurf, AMP, and emerging AI coding agents
🔍 Enhanced Search: Better relevance ranking and query understanding
📊 Analytics Dashboard: Usage patterns, spec health trends over time
🧪 Test Generation: Auto-generate tests from acceptance criteria

Medium Term:

🔄 Real-time Sync: Multi-user collaboration on specifications
🤖 Agent Plugins: Native plugins for Claude Code, Cursor, and other agents
� EntVerprise Features: SSO, audit logs, compliance reporting

Long Term:

🌐 Spec Marketplace: Share and discover specification templates
🧠 Predictive Memory: Anticipate what specs an agent will need
🔗 Cross-Project Memory: Share knowledge across related projects
🤝 Agent Collaboration: Multiple agents sharing the same memory layer

The Vision: SpecMem is a bet on the future of software development. We believe AI coding agents will become the primary way software is built. When that happens, the teams with the best Agent Experience will ship faster, with fewer bugs, and less rework.

Specs shouldn't be documents that rot. They should be memory that agents use.

SpecMem is developed by Superagentic AI as part of the Kiroween Hackathon, December 2025.