From skills-by-amrit
Automated persistent memory system for AI agents โ captures decisions, context, and learnings across sessions using file-based protocols. Works in Antigravity, Cursor, Claude Code, and any agent that can read/write files.
npx claudepluginhub boparaiamrit/skills-by-amritThis skill uses the workspace's default tool permissions.
> Automated context preservation across AI coding sessions โ no hooks, no APIs, no external services.
Guides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Migrates code, prompts, and API calls from Claude Sonnet 4.0/4.5 or Opus 4.1 to Opus 4.5, updating model strings on Anthropic, AWS, GCP, Azure platforms.
Analyzes BMad project state from catalog CSV, configs, artifacts, and query to recommend next skills or answer questions. Useful for help requests, 'what next', or starting BMad.
Automated context preservation across AI coding sessions โ no hooks, no APIs, no external services.
Every AI coding session starts from scratch. You explain the same architecture, repeat the same decisions, and lose the context you built in previous sessions. This skill solves that by creating a file-based memory protocol that any AI agent can follow.
Unlike claude-mem (which requires Claude Code hooks and a worker service), this system works in any agent that can read and write files โ Antigravity, Cursor, Claude Code, Gemini CLI, Cline, and more.
| Asset | Location | Purpose |
|---|---|---|
| Command | commands/memory.md | /memory init, /memory write, /memory compress |
| Workflow | workflows/memory-sync.md | End-to-end memory sync workflow |
| Cursor Rule | cursor-rules/memory-protocol.mdc | Auto-enforced memory protocol for Cursor |
| Universal Rule | rules/memory-protocol.md | Memory protocol for any agent |
| State Tool | scripts/planning-tools.cjs | Deterministic state management CLI |
.planning/
โโโ MEMORY.md # ๐ง Compressed project brain (~300 lines max)
โโโ sessions/
โ โโโ YYYY-MM-DD-session-N.md # Session logs (auto-pruned to last 10)
โ โโโ _archive/ # Older sessions compressed here
โโโ decisions/
โ โโโ DECISIONS.md # Chronological decision log (append-only)
โโโ context/
โ โโโ architecture.md # Architecture decisions record
โ โโโ patterns.md # Established code patterns
โ โโโ gotchas.md # Known issues, bugs, workarounds
โ โโโ tech-debt.md # Known technical debt
โโโ handoffs/
โ โโโ LATEST.md # Current session's handoff note
โ โโโ _history/ # Previous handoffs (auto-archived)
โโโ config.json # Optional: memory configuration
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ SESSION START โ
โ โ
โ 1. Agent reads MEMORY.md (project brain) โ
โ 2. Agent reads handoffs/LATEST.md (last session) โ
โ 3. Agent has full context โ no questions needed โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ DURING SESSION โ
โ โ
โ 4. Agent works normally on tasks โ
โ 5. On significant decisions โ append to DECISIONS.md โ
โ 6. On discovering bugs โ append to gotchas.md โ
โ 7. On architecture changes โ update architecture.md โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ SESSION END โ
โ โ
โ 8. Archive LATEST.md to handoffs/_history/ โ
โ 9. Agent creates session log in sessions/ โ
โ 10. Agent writes new handoffs/LATEST.md โ
โ 11. Agent compresses updates into MEMORY.md โ
โ 12. If MEMORY.md > 300 lines, run compression โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
ALWAYS do this at the start of every conversation involving project work:
Look for .planning/MEMORY.md in the project root.
- If .planning/ doesn't exist โ this is a new project, skip to Initialization section
- If .planning/ exists but MEMORY.md doesn't โ partial setup, run /memory init
Read .planning/MEMORY.md to understand:
- Project overview and current state
- Key architectural decisions
- Active work streams
- Known issues and workarounds
- What happened in recent sessions
Check if .planning/handoffs/LATEST.md exists.
IF IT EXISTS, read it to understand:
- What was being worked on last
- What was completed
- What's pending
- Any blockers or open questions
IF IT DOESN'T EXIST:
- This is normal for newly initialized projects
- Skip to Step 4 โ rely on MEMORY.md alone
- Do NOT error or warn the user
Briefly acknowledge what you know from memory:
"I see from memory that we're working on [X], last session we [Y],
and there's a known issue with [Z]."
If LATEST.md was missing, say:
"I loaded project memory. No previous handoff found โ this may be a new memory setup."
Capture these types of decisions:
| Category | Examples |
|---|---|
| Architecture | Database schema changes, API endpoint design, auth flow choice |
| Technology | Framework selection, library choice, build tool configuration |
| Patterns | State management approach, error handling strategy, testing patterns |
| Trade-offs | Performance vs readability, DRY vs explicit, monolith vs microservices |
| Breaking Changes | API version bumps, data migration strategies, deprecation plans |
Do NOT capture: Minor variable naming, formatting changes, obvious fixes.
Append to .planning/decisions/DECISIONS.md:
## [DATE] โ [Topic]
**Decision:** [What was decided]
**Rationale:** [Why this was chosen]
**Alternatives:** [What was considered but rejected]
**Impact:** [What this affects]
Append to .planning/context/gotchas.md:
## [Component/Area]
**Issue:** [Description]
**Workaround:** [How to handle it]
**Root Cause:** [If known]
**Date Discovered:** [DATE]
Update .planning/context/architecture.md:
## [System/Module Name]
**Pattern:** [What pattern is used]
**Rationale:** [Why this approach]
**Dependencies:** [What it depends on]
**Last Updated:** [DATE]
Append to .planning/context/tech-debt.md:
## [Area]
**Debt:** [What needs fixing]
**Severity:** low | medium | high | critical
**Estimated Effort:** [Time estimate]
**Date Identified:** [DATE]
After completing significant work milestones (feature complete, major fix, etc.), proactively ask:
"Would you like me to save progress to memory now? This captures today's work for future sessions."
This prevents data loss if the user forgets to end the session properly.
ALWAYS do this before ending a significant work session:
IF .planning/handoffs/LATEST.md exists:
1. Create .planning/handoffs/_history/ if it doesn't exist
2. Move LATEST.md to _history/YYYY-MM-DD-HH-MM.md (use current timestamp)
This preserves the previous session's handoff โ never lose context.
Session Numbering Algorithm:
1. List all files matching pattern: .planning/sessions/YYYY-MM-DD-session-*.md
(where YYYY-MM-DD is TODAY's local date)
2. Extract the N value from each filename
3. Set N = (highest N found) + 1
4. If no sessions exist for today, N = 1
Example:
- Today: 2024-02-09
- Existing: 2024-02-09-session-1.md, 2024-02-09-session-2.md
- New file: 2024-02-09-session-3.md
Create .planning/sessions/YYYY-MM-DD-session-N.md:
# Session: [DATE] โ Session [N]
## Duration
[Approximate time spent]
## Objective
[What was the goal]
## Completed
- [x] [Task 1 โ brief description]
- [x] [Task 2 โ brief description]
## In Progress
- [ ] [Task โ what remains]
## Decisions Made
- [Decision 1 โ brief]
- [Decision 2 โ brief]
## Issues Encountered
- [Issue 1 โ brief]
## Files Modified
- `path/to/file.ts` โ [what changed]
- `path/to/other.py` โ [what changed]
## Next Steps
1. [What should happen next]
2. [Follow-up items]
Create NEW .planning/handoffs/LATEST.md:
# Handoff: [DATE]
## Last Session Summary
[One paragraph of what happened]
## Current State
- **Working on:** [Active task]
- **Blocked by:** [Any blockers, or "nothing"]
- **Branch:** [Git branch if applicable]
## Immediate Next Steps
1. [Most important next thing]
2. [Second priority]
3. [Third priority]
## Open Questions
- [Any unresolved questions]
## Watch Out For
- [Any gotchas the next session should know about]
Update .planning/MEMORY.md with any new information from this session. Keep it under 300 lines by compressing older entries.
# ๐ง Project Memory
> Auto-maintained by persistent-memory skill
> Last updated: [DATE]
## ๐ Project Overview
[2-3 sentence project description]
- **Tech Stack:** [languages, frameworks, databases]
- **Repository:** [repo info]
- **Status:** [active development | maintenance | etc.]
## ๐๏ธ Architecture
[Key architectural decisions โ bullet points]
- [Pattern 1]: [why]
- [Pattern 2]: [why]
## ๐ Current State
### Active Work
- [What's being worked on right now]
### Recently Completed
- [Last 3-5 completed items with dates]
### Blocked / Waiting
- [Anything blocked and why]
## ๐ Key Decisions
[Last 10 significant decisions, newest first]
1. [DATE] โ [Decision]: [Brief rationale]
2. [DATE] โ [Decision]: [Brief rationale]
## โ ๏ธ Known Issues & Gotchas
- [Issue 1]: [Workaround]
- [Issue 2]: [Workaround]
## ๐ Patterns & Conventions
- [Pattern 1]: [How to use it]
- [Pattern 2]: [How to use it]
## ๐๏ธ Recent Sessions
| Date | Summary |
|------|---------|
| [DATE] | [One-line summary] |
| [DATE] | [One-line summary] |
| [DATE] | [One-line summary] |
When MEMORY.md exceeds 300 lines, run compression:
1. COUNT current lines in MEMORY.md
2. IF lines <= 300:
- No compression needed
- Exit
3. COMPRESS in this order (stop when under 300 lines):
a. Recent Sessions table:
- Keep only last 5 entries
- Remove older rows from table
b. Key Decisions:
- Keep only last 10 decisions
- Move older decisions to context/architecture.md (if significant)
- Or delete (if superseded)
c. Recently Completed:
- Keep only last 5 items
- Remove older items (they're in session logs anyway)
d. Known Issues:
- Remove any issues marked as resolved
- Merge related issues into single entries
e. Patterns & Conventions:
- Move detailed patterns to context/patterns.md
- Keep only one-liner summaries in MEMORY.md
4. ARCHIVE old session logs:
- Move sessions older than 30 days to sessions/_archive/
- Use filename: _archive/YYYY-MM-compressed.md
- Combine multiple sessions into monthly summaries
5. VERIFY:
- Re-count lines
- If still > 300, repeat step 3 more aggressively
sessions/_archive/2024-02-compressed.md:
# Archived Sessions: February 2024
## Summary
- Total sessions: 15
- Major accomplishments: [list]
- Major decisions: [list]
## Session Index
| Date | Session | Summary |
|------|---------|---------|
| 2024-02-01 | 1 | [summary] |
| 2024-02-01 | 2 | [summary] |
...
To bootstrap memory for an existing project, run the /memory init command or workflow.
The initialization scan follows this algorithm:
1. DETECT PROJECT TYPE:
- Look for package.json โ Node.js/JavaScript/TypeScript
- Look for requirements.txt/pyproject.toml โ Python
- Look for go.mod โ Go
- Look for Cargo.toml โ Rust
- Look for pom.xml/build.gradle โ Java
- Look for *.sln/*.csproj โ .NET
- No matches โ Generic project
2. EXTRACT TECH STACK:
- Parse dependency files for frameworks (React, Django, etc.)
- Identify major libraries
- Note database connections (if visible in config)
3. ANALYZE STRUCTURE:
- Count files by extension
- Identify main source directories
- Detect test directories
- Note documentation presence
4. IDENTIFY PATTERNS:
- Look for common patterns (MVC, repository pattern, etc.)
- Check for existing style guides (.editorconfig, .prettierrc)
- Note linting configuration
5. GENERATE INITIAL MEMORY:
- Write project overview based on package.json/readme info
- Document detected architecture
- List identified patterns
- Create empty but structured context files
| File | Initial Content |
|---|---|
MEMORY.md | Project overview from scan |
DECISIONS.md | Empty with template header |
architecture.md | Detected patterns |
patterns.md | Empty with template header |
gotchas.md | Empty with template header |
tech-debt.md | Empty with template header |
LATEST.md | "Memory initialized" note |
When multiple agents (or multiple terminals) may edit memory concurrently:
1. ALWAYS read the latest version of files before editing
2. Keep edits small โ append-only where possible
3. Use git for conflict resolution:
- git pull before reading memory
- git add && git commit after writing memory
1. Git will detect the conflict on push
2. The later agent should:
- Pull the latest version
- Merge manually (memory files are human-readable)
- Push the merged version
3. For append-only files (DECISIONS.md, gotchas.md):
- Simply keep both entries โ duplicates are better than data loss
# Start of session
git pull origin main
# End of session (after memory write)
git add .planning/
git commit -m "chore: update project memory"
git push origin main
| Error | Cause | Recovery |
|---|---|---|
MEMORY.md is empty | Corrupted or deleted | Re-run /memory init to regenerate |
MEMORY.md is unreadable | Malformed markdown | Restore from git, or regenerate from context/ files |
.planning/ partially exists | Interrupted init | Delete .planning/ and re-run /memory init |
Write permission denied | File locked or permissions | Check file permissions, close other editors |
Session numbering conflict | Two sessions same second | Use timestamp with seconds: YYYY-MM-DD-HHMMSS-session |
If MEMORY.md is corrupted and git history isn't available:
1. Check context/ subdirectory โ these files contain detailed info
2. Read recent session logs in sessions/
3. Read handoffs/_history/ for recent handoffs
4. Reconstruct MEMORY.md from these sources
5. Re-run /memory init to validate structure
Add to your GEMINI.md or .gemini/GEMINI.md:
## ๐ง Automatic Memory Protocol
ALWAYS at the START of every conversation involving project work:
1. Check if `.planning/MEMORY.md` exists in the project
2. If yes, read it FIRST before doing anything else
3. Also read `.planning/handoffs/LATEST.md` if it exists
4. Use this context to inform your work
ALWAYS at the END of significant work sessions:
1. Archive previous LATEST.md to handoffs/_history/
2. Update `.planning/MEMORY.md` with new learnings
3. Write `.planning/handoffs/LATEST.md` for the next session
4. Append any decisions to `.planning/decisions/DECISIONS.md`
5. Keep MEMORY.md under 300 lines (compress older entries)
Add the memory-protocol.mdc rule to .cursor/rules/.
Add the memory.md command to .claude/commands/.
This system is designed to be token-efficient:
โ ๏ธ Note: Token counts vary significantly based on content. Code-heavy files may use 2x more tokens than prose. These are estimates for typical documentation-style content.
Compare to claude-mem's progressive disclosure (50-1,000 tokens per search result) โ this is comparable but zero-infrastructure.
Create .planning/config.json for customization:
{
"memory": {
"auto_read": true,
"auto_write": false,
"max_memory_lines": 300,
"max_sessions": 10,
"compress_on_write": true,
"archive_after_days": 30,
"preserve_handoff_history": true
}
}
Add to your project's .gitignore:
# Preserve memory but ignore secrets
# Don't add these lines โ just ensure .planning/ is NOT in .gitignore
# If you have secrets in memory (you shouldn't), ignore them:
# .planning/secrets/
# .planning/*.secret.md
Best practice: Commit .planning/ to version control. This enables:
โ Don't store raw conversation logs โ too large, too noisy โ Don't let MEMORY.md grow unbounded โ compress aggressively โ Don't duplicate information across files โ single source of truth โ Don't include sensitive data (API keys, passwords) in memory files โ Don't skip the handoff note โ it's the most valuable part โ Don't manually edit MEMORY.md โ let the agent maintain it โ Don't ignore multi-agent scenarios โ use git for coordination
โ
Do keep MEMORY.md under 300 lines at all times
โ
Do write a handoff note at the end of EVERY session
โ
Do include "watch out for" notes in handoffs
โ
Do compress older decisions into one-liners
โ
Do reference specific files and line numbers in gotchas
โ
Do commit .planning/ to version control
โ
Do use local date (not UTC) for session filenames
โ
Do archive previous handoffs before overwriting
โ
Do prompt for memory save after significant milestones