project-memory

name	project-memory
description	Complementary project memory system for AI agents. Records observations, decisions, and session summaries to maintain context across development sessions. Prevents duplicate work, tracks architectural decisions, and enables token-efficient context retrieval.
projectType	all

Project Memory Skill

Purpose

Enable AI agents to maintain persistent project context across sessions using a complementary (non-intrusive) approach. The memory system records what was done, what was learned, and what decisions were made — so future sessions start with relevant context instead of re-reading the entire codebase.

When to Use

• Before implementing a new feature: Search memory to check if similar work was done before
• After completing a significant task: Log an observation to record what was done
• At the end of a session: Summarize the session for future reference
• When starting a complex session: Read context to understand project history

Complementary Approach

This skill is COMPLEMENTARY, not mandatory. The AI agent uses memory WHEN USEFUL, not at every step.

• Simple tasks (fix typo, format code): Skip memory entirely → 0 token overhead
• Complex tasks (new feature, architecture change): Use memory → save 10-30x tokens vs re-reading code

Available Commands

1. Log an Observation (Post-Task)

Record what was done after completing a significant task:

heraspec memory log \
  --type <decision|bugfix|feature|refactor|discovery|change> \
  --title "Short descriptive title" \
  --narrative "Detailed description of what was done and why" \
  --concepts "tag1,tag2,tag3" \
  --files-modified "src/file1.ts,src/file2.ts"

Observation types:

Type	Icon	When to Use
decision	⚖️	Architecture or design decisions with rationale
bugfix	🔴	Bug fixes with root cause
feature	🟢	New feature implementations
refactor	🔄	Code restructuring or optimization
discovery	🔵	Important findings about codebase or behavior
change	✅	General code changes

2. Search Memory (Pre-Implementation)

Check if related work exists before implementing something new:

heraspec memory search "authentication middleware"
heraspec memory search --type feature --concepts "auth,login"
heraspec memory search --id 42   # Get full details of observation #42

3. Generate Context (Session Start)

Get a summary of recent project activity:

heraspec memory context           # Print to stdout
heraspec memory context --output file  # Write to heraspec/memory/context.md

4. Summarize Session (Session End)

Record what was accomplished in this session:

heraspec memory summarize \
  --request "What the user asked for" \
  --completed "What was done" \
  --learned "Key insights discovered" \
  --next-steps "What remains to be done" \
  --files-edited "src/file1.ts,src/file2.ts"

5. View Status

Check memory statistics:

heraspec memory status    # Observation count, top concepts, top files
heraspec memory timeline  # Chronological view of activity

6. Token Analytics Report

View detailed token usage vs savings comparison per project:

heraspec memory analytics            # Table + chart of token economics
heraspec memory analytics --history  # Includes 13 latest database size changes

Output includes:

• Table: Project name, Operations count, Tokens With Memory, Tokens Without Memory, Savings %, DB Size
• Bar Chart: Visual comparison of tokens avoided per project
• Totals: Aggregated savings across all projects
• History (Optional): A chronological delta chart of how the .db file size has changed over time.

7. Maintenance

heraspec memory prune 90  # Delete observations older than 90 days

Workflow for AI Agents

When to Use Memory (Decision Tree)

Receive task from user
├── Is it a simple/trivial task? → Skip memory, just do it
├── Is it a new feature or significant change?
│   ├── Search memory: "heraspec memory search <relevant keywords>"
│   ├── Results found? → Read relevant observations, avoid duplicating work
│   └── No results? → Proceed normally
├── After completing the task:
│   ├── Was it significant? → Log observation
│   └── Was it trivial? → Skip logging
└── End of session?
    └── Multiple tasks completed? → Create session summary

Key Principles

1. Don't force it: Only use memory when it genuinely saves time or prevents mistakes
2. Quality over quantity: One detailed observation is better than ten shallow ones
3. Concepts are crucial: Good concept tags (auth, database, api, ui) make search effective
4. Files matter: Recording which files were modified helps future agents navigate

Configuration

Memory configuration is stored in heraspec/memory/config.json:

{
  "totalObservationCount": 50,
  "fullObservationCount": 5,
  "sessionCount": 5,
  "maxTokens": 6000,
  "showLastSummary": true
}

Token Economics

Action	Token Cost	Token Savings
Read context	~2,000-4,000	vs ~50,000-120,000 re-reading codebase
Search memory	~500-1,000	vs ~5,000-15,000 duplicate implementation
Log observation	~200-500	Investment for future sessions
Smart explore (outline)	~1,000-2,000	vs ~12,000+ full file read

To view a live analytics dashboard of token savings, run:

heraspec memory analytics

Bootstrapping Existing Projects

If you are adding the project-memory skill to an older project that already has historical specs and changes (in heraspec/specs/ and heraspec/archives/), you can bootstrap the memory system without writing any code.

Simply provide this prompt to the AI agent once:

Use the project-memory skill.
Please bootstrap the project memory from all our existing specs and archives.
Open the folders: heraspec/specs/ and heraspec/archives/
For EVERY sub-folder/file inside, read it to understand the context, then run:

heraspec memory log \
  --type feature \
  --title "[Extract spec/change title]" \
  --narrative "[Short summary of what was implemented]" \
  --concepts "[Extract key tags/technologies]" \
  --files-modified "[Extract affected files]"

Repeat this until all old specs are migrated into the memory system.

Alternatively, use the built-in CLI command (faster, no AI tokens spent):

heraspec memory bootstrap        # Interactive — prompts for confirmation
heraspec memory bootstrap --yes  # Non-interactive — auto-confirm

This command will automatically scan heraspec/specs/, heraspec/archives/, and heraspec/changes/, extract title/narrative/files from each markdown spec, and insert them into the memory database.

Note: Duplicate titles are automatically skipped, so running the command multiple times is safe.

Agent-Triggered Reporting

When the user asks the AI agent to view memory reports, analytics, or token savings — the agent should run the CLI command and return the output:

User: "Show me the memory analytics report"
User: "How many tokens has the memory system saved?"
User: "Give me a token usage report"

Agent action: Execute the following command and display the output to the user:

heraspec memory analytics

For a quick status check:

heraspec memory status

For a timeline view:

heraspec memory timeline

Limitations

• Memory is project-local (stored in heraspec/memory/)
• Requires better-sqlite3 npm package
• FTS5 search is keyword-based, not semantic
• Agent must decide when to use memory (complementary approach)