memory-system
Skill9 starsChanged 3 months agoApache-2.0View on GitHub
Persistent cross-session memory management. Enables agents to remember user preferences, project conventions, and past decisions across different sessions using a structured MEMORY.md index and topic files. When the user says 'remember this', 'save this for later', 'don't forget', or when starting a new session and needing to recall past context. Also when /remember workflow is invoked.
9 other projects use a version of this, 2 of them edited.
Adopted by
Most recently taken up by
- bojieli/ai-agent-book-projectstheir own version, first seen Oct 9, 2026
- joelhooks/joelclawtheir own version, first seen Oct 8, 2026
- vudovn/ag-kitedited, first seen Oct 8, 2026
- bojieli/ai-agent-booktheir own version, first seen Oct 8, 2026
- vudovn/antigravity-kitedited, first seen Oct 8, 2026
- Mlu-ctrl-alt-design/claude-skillstheir own version, first seen May 23, 2026
Other versions9 projects use a version of this.
Word for word · 0
None found.
Edited · 2
- vudovn/ag-kit★ 8.2k98% same
- vudovn/antigravity-kit★ 8.2k98% same
Wrote their own version · 7
- bojieli/ai-agent-book-projects★ 53ksame name
- bojieli/ai-agent-book★ 53ksame name
- kangarooking/system-prompt-skills★ 178same name
- joelhooks/joelclaw★ 65same name
- Mlu-ctrl-alt-design/claude-skills★ 1same name
- Dimks777/aiclub★ 0same name
- Victoriakaey/build-reliable-agents★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository36 other files it gives its agents.
- .claude/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- api-designSkill
- architectureSkill
- bash-linuxSkill
- batch-operationsSkill
- behavioral-modesSkill
- claude-code-worktreesSkill
- clean-codeSkill
- context-compressionSkill
- coordinator-modeSkill
- database-designSkill
- deployment-proceduresSkill
- documentation-templatesSkill
- error-handlingSkill
- github-issuesSkill
- github-pmSkill
- github-projectSkill
- git-workflowSkill
- goal-builderSkill
- graphifySkill
- intelligent-routingSkill
- lint-and-validateSkill
- lint-fixSkill
- performance-profilingSkill
- powershell-windowsSkill
- pre-commit-verifySkill
- red-team-tacticsSkill
- release-vsixSkill
- run-testsSkill
- server-managementSkill
- setup-testingSkill
- testing-patternsSkill
- test-triageSkill
- uncle-bob-craftSkill
- vulnerability-scannerSkill
The file
We split this skill into the rules it gives an agent
6 rules. 0 are common, 6 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 6 edited versions we read keep these.
6
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 127
Check if relevant topic file exists
- Distinctive: line 128
If yes → append to existing topic file
- Distinctive: line 129
If no → create new topic file with frontmatter
- Distinctive: line 130
Update MEMORY.md index with one-line pointer
- Distinctive: line 137
If match found → read the referenced topic file
- Distinctive: line 151
Never auto-delete — always ask user first
“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!-- Vendored from ag-kit (github.com/vudovn/ag-kit) @ 20a13da6d4414c7c6ae33db050a9c606eaef9f40 :: .agents/skills/memory-system/SKILL.md. MIT (c) vudovn. -->Memory System — Persistent Cross-Session Memory
Enables agents to remember across sessions. Never re-discover what was already learned.
Overview
The Memory System provides persistent, searchable memory that survives across sessions. Instead of re-explaining preferences, conventions, and past decisions every time, agents read a structured MEMORY.md index and topic files.
Token Impact: +1,000 tokens to load index, but saves 3,000-10,000 tokens by eliminating re-discovery.
Architecture
.agents/memory/
├── MEMORY.md ← Lightweight index (max 200 lines)
├── user-preferences.md ← Topic file: user role, style, tools
├── project-conventions.md ← Topic file: coding standards, patterns
├── tech-decisions.md ← Topic file: past architectural decisions
├── feedback-history.md ← Topic file: what user liked/disliked
└── [topic-name].md ← Additional topic files as neededMEMORY.md Index Format
The index is a lightweight pointer file — short entries that reference topic files for details.
Rules:
- Maximum 200 lines total
- Each entry: ~150 characters max
- Format:
- [type] summary → topic-file.md - Types:
[user][feedback][project][reference]
Example:
# Memory Index
## User
- [user] Prefers dark mode, uses Windows 11, PowerShell → user-preferences.md
- [user] Senior DevOps engineer, 8 years experience → user-preferences.md
- [user] Primary language: English, sometimes Turkish → user-preferences.md
## Project
- [project] Always use bun instead of npm → project-conventions.md
- [project] Tailwind v4 preferred, no v3 → tech-decisions.md
- [project] No purple/violet colors in UI → project-conventions.md
## Feedback
- [feedback] User likes concise responses, no filler → feedback-history.md
- [feedback] User dislikes verbose explanations → feedback-history.md
- [feedback] User prefers tables over bullet lists → feedback-history.md
## Reference
- [reference] Squid proxy runs on port 3128 → infrastructure-notes.md
- [reference] Git workflow: feature branches → main → project-conventions.mdTopic File Format
Each topic file has frontmatter and structured content:
---
type: user | feedback | project | reference
created: 2026-04-01
updated: 2026-04-01
---
# User Preferences
## Development Environment
- OS: Windows 11
- Shell: PowerShell
- Editor: Cursor / Windsurf
- Package Manager: bun (NOT npm)
## Communication Style
- Prefers concise responses
- Likes tables for comparisons
- Dislikes verbose explanationsMemory Taxonomy
| Type | What to Store | Example |
| user | Role, preferences, tools, communication style | "Senior DevOps, prefers dark mode" |
| feedback | What user liked/disliked about agent output | "User said 'too verbose', prefers tables" |
| project | Coding standards, tech choices, conventions | "Use bun not npm, Tailwind v4" |
| reference | Non-sensitive infrastructure notes, public URLs, configs | "Prod API hostname and port" |
What NOT to Save
| Don't Save | Why |
| Secrets, credentials, tokens, passwords, private keys, or API keys | Memory is persistent and may be shared across sessions |
| Information derivable from code | Read package.json instead of memorizing deps |
| Temporary debug context | Clutters memory, not useful later |
| Exact code snippets | Code changes — memory becomes stale |
| File paths that may move | Use glob patterns or descriptions instead |
| Entire conversation transcripts | Memory is for distilled insights only |
Operations
Save (Trigger: user says "remember", "save", "don't forget")
- Identify the information type (user/feedback/project/reference)
- Check if relevant topic file exists
- If yes → append to existing topic file
- If no → create new topic file with frontmatter
- Update MEMORY.md index with one-line pointer
- Confirm to user: "Saved to memory: [summary]"
Recall (Trigger: session start, or "what do you remember about X")
- Read
.agents/memory/MEMORY.mdindex - Scan for relevant entries matching the current task
- If match found → read the referenced topic file
- Apply recalled context silently (don't recite memories unless asked)
Search (Trigger: "do I have any notes about X")
- Grep across
.agents/memory/*.mdfor the search term - Return matching entries with file references
- Offer to read full topic file if user wants details
Prune (Trigger: index exceeds 200 lines)
- Warn: "Memory index is getting large (X lines). Review recommended."
- Suggest merging related entries
- Suggest archiving old entries to
memory/archive/ - Never auto-delete — always ask user first
Session Start Protocol
At the start of every session:
1. Check: Does `.agents/memory/MEMORY.md` exist?
→ YES: Read index. Apply relevant context silently.
→ NO: Continue without memory. Create on first "remember" trigger.
2. Apply memory WITHOUT reciting it.
❌ WRONG: "I remember you prefer dark mode and use bun..."
✅ RIGHT: (silently apply preferences, use bun in commands)
3. Exception: If user asks "what do you remember?" → recite relevant memories.Memory vs. Plan vs. Task
| Artifact | Purpose | Lifespan | Location |
| Memory | Cross-session knowledge | Permanent until pruned | .agents/memory/ |
| Plan | Task breakdown for current project | Until project complete | Project root |
| Task | Progress tracker for current session | Until session ends | Artifact directory |
Memory = what you KNOW. Plan = what you'll DO. Task = what you're DOING NOW.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

