specmem 0.1.4

Unified, embeddable memory layer for AI coding agents built on Spec-Driven Development metadata

SpecMem

🧠 Unified Agent Experience and Pragmatic Memory for Every Coding Agent

The first-ever Agent Experience (AgentEx) platform built for AI coding agents

📚 Documentation • 🚀 Getting Started • ⭐ GitHub

---

🎯 The Problem

Modern coding agents (Kiro, SpecKit, Tessl, Claude Code, Cursor, etc.) can generate files, follow tasks, and implement features, but the industry faces critical challenges:

📄 Markdown Madness & Verbosity

Today's coding agents generate mountains of markdown files. Developers are drowning in CLAUDE.md, AGENTS.md, .cursorrules, requirements.md, design.md... What happens to all these specs after features are built? Nobody has figured out how to turn this chaos into better Agent Experience.

🔒 Vendor Lock-In & Format Fragmentation

Every coding agent uses its own proprietary format. Claude uses CLAUDE.md, Cursor uses .cursorrules, Kiro uses .kiro/specs/. This creates massive IDE lock-in. Switching agents means rewriting all your specs. Your project knowledge is trapped in one tool.

🧠 Agents Have Amnesia

Modern coding agents suffer from catastrophic forgetting. Sessions reset, context is lost, previous decisions vanish. Agents write code without knowing your specs, acceptance criteria, or earlier decisions.

⚡ Wasted Compute & Slow CI

Without understanding what changed, agents trigger full test runs for every tiny change, wasting compute and slowing CI pipelines.

📉 No Agent Experience (AgentEx) Layer

We have DevEx (Developer Experience) for humans. But where is AgentEx for AI coding agents? There's no unified memory layer, no context optimization, no impact analysis.

These issues cause: regressions, misaligned implementations, slow CI pipelines, unpredictable agent behavior, and increased costs.

The industry lacks a Cognitive Memory + Agent Experience platform to fix this

---

💡 The Solution: SpecMem

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

How SpecMem Solves Each Problem

Problem	SpecMem Solution
Markdown Madness	Concise spec templates, auto TL;DRs, living documentation
Vendor Lock-In	Agent-agnostic adapters: read ANY format, output to ANY agent
Agent Amnesia	Persistent cognitive memory with semantic search
Wasted Compute	SpecImpact selects only impacted specs/tests to execute
No AgentEx	Complete Agent Experience layer with context optimization

# Using pip
pip install specmem

# Using uv (recommended - faster)
uv pip install specmem

# Or run directly with uvx
uvx specmem --help

from specmem import SpecMemClient

sm = SpecMemClient()
bundle = sm.get_context_for_change(["auth/service.py"])
print(bundle.tldr)

---

✨ Key Features

Core Features

Feature	Description
🔌 Multi-Framework Adapters	Parse specs from Kiro, SpecKit, Tessl, Claude Code, Cursor, Codex, Factory, Warp, Gemini CLI
🧠 Intelligent Memory	Vector-based semantic search with LanceDB, ChromaDB, Qdrant, or AgentVectorDB
📊 SpecImpact Graph	Bidirectional relationships between specs, code, and tests
⏱️ SpecDiff Timeline	Track spec evolution, detect drift, find contradictions
✅ SpecValidator	Quality assurance with 6 validation rules (structure, timeline, duplicates, constraints, acceptance criteria, contradictions)
📈 Spec Coverage	Analyze gaps between acceptance criteria and tests with suggestions
🎯 Test Mapping Engine	Map tests to specs across pytest, jest, vitest, and more
💚 Health Score	Project health grades (A-F) with improvement suggestions
🌐 Web UI	Interactive dashboard with live sync, filtering, and WebSocket updates

Advanced Features

Feature	Description
☁️ Cloud Embeddings	Support for OpenAI, Google, Together AI embedding providers
📜 Coding Guidelines	Aggregate and view guidelines from Kiro steering, CLAUDE.md, .cursorrules
🔄 Spec Lifecycle	Prune stale specs, generate specs from code, compress verbose specs
🔍 Kiro Session Search	Index and search Kiro chat sessions for context
⚙️ Kiro Config Indexer	Index hooks, steering files, and MCP configurations
📤 Static Dashboard	Export specs to a static HTML dashboard for GitHub Pages
🤖 GitHub Action	CI integration with coverage thresholds and PR comments
🔌 MCP Server	Model Context Protocol server for AI agent integration
⚡ Kiro Powers	Native Kiro IDE integration as a Power
🌊 Streaming Context API	Token-aware context optimization with streaming support

---

🔄 The Killer Feature

Swap agents without losing context. SpecMem creates a unified, normalized, agent-agnostic context layer.

Switch from Kiro → SpecKit → Tessl → Claude Code → Cursor without rewriting spec files or losing project knowledge.

┌─────────────────────────────────────────────────────────────────┐
│                         Your Project                            │
├─────────────────────────────────────────────────────────────────┤
│  .kiro/specs/   .speckit/   .tessl/   Claude.md   cursor.json   │
│       │             │          │          │            │         │
│       └─────────────┴──────────┴──────────┴────────────┘         │
│                           │                                      │
│                    ┌──────▼──────┐                               │
│                    │   SpecMem   │                               │
│                    │  Adapters   │                               │
│                    └──────┬──────┘                               │
│                           │                                      │
│                    ┌──────▼──────┐                               │
│                    │   SpecIR    │  ← Canonical Representation   │
│                    └──────┬──────┘                               │
│                           │                                      │
│         ┌─────────────────┼─────────────────┐                    │
│         │                 │                 │                    │
│  ┌──────▼──────┐   ┌──────▼──────┐   ┌──────▼──────┐            │
│  │ Vector DB   │   │ SpecImpact  │   │  SpecDiff   │            │
│  │ (LanceDB)   │   │   Graph     │   │  Timeline   │            │
│  └─────────────┘   └─────────────┘   └─────────────┘            │
│                           │                                      │
│                    ┌──────▼──────┐                               │
│                    │ AgentXPack  │  ← Output for any agent       │
│                    └─────────────┘                               │
└─────────────────────────────────────────────────────────────────┘

---

🧠 Living Documentation & Memory

SpecMem transforms your specifications into living documentation that:

1. Stays in sync - File watcher detects changes and re-indexes automatically
2. Provides context - AI agents query specs via MCP to understand your project
3. Tracks coverage - See which acceptance criteria have tests
4. Shows relationships - Impact graph connects specs ↔ code ↔ tests

How it acts as "memory" for agents:

┌─────────────────────────────────────────────────────────────────┐
│  Agent asks: "What are the auth requirements?"                  │
│                           │                                      │
│                    ┌──────▼──────┐                               │
│                    │   SpecMem   │  ← Semantic search            │
│                    │   Memory    │                               │
│                    └──────┬──────┘                               │
│                           │                                      │
│  Returns: Relevant specs, related code, suggested tests         │
└─────────────────────────────────────────────────────────────────┘

🚀 Quick Start

Try It Now (Demo)

# See SpecMem in action with its own specs
specmem demo

This launches the Web UI with SpecMem's own specifications - dogfooding at its finest!

CLI

# Initialize SpecMem in your project
specmem init

# Initialize with Kiro hooks for automation
specmem init --hooks

# Scan and index your specifications
specmem scan

# Build the Agent Experience Pack
specmem build

# Query your specs
specmem query "What are the authentication requirements?"

# Analyze impact of code changes
specmem impact --files src/auth/service.py

# Check spec coverage
specmem cov

# Get test suggestions for uncovered criteria
specmem cov suggest auth-feature

# Check project health score
specmem health

# Validate spec quality
specmem validate

# View spec diff/history
specmem diff auth.login
specmem history auth.login

# Lifecycle management
specmem prune --orphaned          # Archive orphaned specs
specmem generate src/             # Generate specs from code
specmem compress --all            # Compress verbose specs

# View coding guidelines
specmem guidelines

# Kiro configuration
specmem kiro-config               # Show all Kiro config
specmem steering --file src/app.py  # Get applicable steering

# Session search (Kiro)
specmem sessions search "auth"    # Search chat sessions
specmem sessions link             # Link sessions to specs

# Export static dashboard
specmem export data               # Export spec data to JSON
specmem export build              # Build static HTML dashboard

# Graph commands
specmem graph impact src/auth.py  # Show affected specs/tests
specmem graph show spec:auth      # Show node relationships
specmem graph export --format dot # Export graph

# Launch Web UI
specmem demo

Python API

from specmem import SpecMemClient

# Initialize client
sm = SpecMemClient()

# Get context for code changes
bundle = sm.get_context_for_change(["auth/service.py"])
print(bundle.tldr)

# Query specifications
specs = sm.query("authentication requirements")

# Get impacted specs for changes
impacted = sm.get_impacted_specs(["auth/service.py"])

# Check for spec drift
drift = sm.get_drift_report()

# Analyze spec coverage
coverage = sm.get_coverage()
print(f"Coverage: {coverage.coverage_percentage:.1f}%")

---

📦 Output: Agent Experience Pack

SpecMem generates a .specmem/ directory containing everything your agents need:

.specmem/
├── agent_memory.json      # All specs with metadata and rankings
├── agent_context.md       # Human-readable summary
├── knowledge_index.json   # Keyword → SpecBlock mapping
├── impact_graph.json      # Code ↔ Spec relationships
└── vectordb/              # Embedded vector storage

---

⚡ Built for Kiro

SpecMem was built during Kiroween 2025 with first-class Kiro support. Your .kiro/specs/ become living, searchable agent memory.

⚡ Kiro Powers Integration

Install SpecMem as a Kiro Power for seamless IDE integration:

• Query specs without leaving Kiro
• Get context-aware suggestions in real-time
• Analyze impact of changes instantly

🔗 MCP Server

Full Model Context Protocol support. Kiro's agent can query your specs, analyze impact, and get optimized context automatically.

// .kiro/settings/mcp.json
{
  "mcpServers": {
    "specmem": {
      "command": "specmem-mcp",
      "args": [],
      "env": { "SPECMEM_WORKSPACE": "${workspaceFolder}" },
      "autoApprove": ["specmem_query", "specmem_tldr", "specmem_coverage"]
    }
  }
}

Available MCP Tools:

Tool	Description
specmem_query	Search specifications by natural language
specmem_impact	Analyze change impact on specs and tests
specmem_context	Get optimized context bundle for files
specmem_tldr	Get TL;DR summary of key specs
specmem_coverage	Analyze spec coverage and test gaps
specmem_validate	Validate specifications for quality issues

📄 Native Kiro Adapter

First-class support for .kiro/specs/ structure:

File	What SpecMem Extracts
requirements.md	User stories, acceptance criteria, constraints
design.md	Architecture decisions, component interfaces
tasks.md	Implementation checklist, progress tracking

🎣 Hooks & Steering

SpecMem includes pre-configured hooks and steering files:

.kiro/
├── settings/mcp.json       # MCP server config
├── hooks/
│   ├── spec-coverage.yaml  # Check coverage on test save
│   ├── spec-validation.yaml # Validate on spec edit
│   └── impact-analysis.yaml # Analyze impact on code change
└── steering/
    ├── specmem-development.md  # Always included
    ├── spec-writing.md         # When editing specs
    └── python-style.md         # When editing Python

See Kiro Integration Guide for details.

---

🤖 GitHub Action

Integrate SpecMem into your CI/CD pipeline:

# .github/workflows/specmem.yml
name: Spec Analysis
on: [pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: SuperagenticAI/specmem/.github/actions/specmem@main
        with:
          commands: cov,health,validate
          comment_on_pr: true
          coverage_threshold: 80
          health_threshold: B

Features:

• 📊 Coverage, health, and validation checks
• 💬 Automatic PR comments with results
• 🚦 Configurable thresholds for quality gates
• 📈 Static dashboard deployment to GitHub Pages

---

📤 Static Dashboard

Export your specs to a static HTML dashboard:

# Generate and preview locally
specmem export data
specmem export build
python -m http.server -d .specmem/static 8080

Or deploy to GitHub Pages with the dashboard action:

- uses: SuperagenticAI/specmem/.github/actions/specmem-dashboard@main
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}

---

🔌 Supported Frameworks

Spec-Driven Development (Priority)

Framework	Adapter	File Patterns
Kiro	kiro	.kiro/specs/**/*.md
SpecKit	speckit	.speckit/**/*.yaml
Tessl	tessl	.tessl/**/*.md

Commercial Coding Agents

Framework	Adapter	File Patterns
Claude Code	claude	Claude.md, CLAUDE.md
Cursor	cursor	cursor.json, .cursorrules
Codex	codex	.codex/**/*.md
Factory	factory	.factory/**/*.yaml
Warp	warp	.warp/**/*.md
Gemini CLI	gemini	GEMINI.md, .gemini/**/*.md

---

🗄️ Vector Database Backends

SpecMem supports multiple vector database backends:

Backend	Install	Best For
LanceDB (default)	pip install specmem[local]	Local development, no server needed
ChromaDB	pip install specmem[chroma]	Local/embedded with persistence
Qdrant	pip install specmem[qdrant]	Production, distributed deployments
AgentVectorDB	Built-in	Lightweight, in-memory

Switch backends:

specmem vector-backend chroma

---

☁️ Cloud Embedding Providers

Use cloud embedding providers for better semantic search:

Provider	Install	Model
OpenAI	pip install specmem[openai]	text-embedding-3-small
Google	pip install specmem[google]	embedding-001
Together AI	pip install specmem[together]	togethercomputer/m2-bert

Configure in .specmem.toml:

[embedding]
provider = "openai"
model = "text-embedding-3-small"

---

✅ Spec Validation Rules

SpecMem validates your specifications with 6 built-in rules:

Rule	What It Checks
Structure	Required sections (requirements, design, tasks) exist
Timeline	Tasks follow logical order, no circular dependencies
Duplicates	No duplicate acceptance criteria or requirements
Constraints	Acceptance criteria are testable and measurable
Acceptance Criteria	EARS pattern compliance, INCOSE quality rules
Contradictions	No conflicting requirements across specs

Run validation:

specmem validate
specmem validate --spec auth-feature --format json

---

📖 Documentation

Full documentation is available at superagenticai.github.io/specmem

• Installation Guide
• Quick Start
• User Guide
• CLI Reference
• Python API
• Advanced Topics

---

🛠️ Development

# Clone the repository
git clone https://github.com/SuperagenticAI/specmem.git
cd specmem

# Using uv (recommended)
uv sync --dev
uv run pytest

# Or using pip
pip install -e ".[dev]"
pytest

Using uv

SpecMem supports uv for fast dependency management:

# Install uv if you haven't
curl -LsSf https://astral.sh/uv/install.sh | sh

# Sync dependencies from lock file
uv sync

# Run specmem commands
uv run specmem --help

# Run tests
uv run pytest

# Add a new dependency
uv add <package>

---

📄 License

AGPL-3.0 - see LICENSE for details.

For commercial licensing options, contact [e-mail]

---

🏢 About

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