memory-system
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.
How do I install this agent skill?
npx skills add https://github.com/vudovn/ag-kit --skill memory-systemIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill implements a persistent memory system for agents to store user preferences and project context in local markdown files. It includes important security-positive guidelines that explicitly instruct the agent not to save secrets or credentials. The primary security risk is the possibility of indirect prompt injection, where instructions stored in memory could be executed in future sessions.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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 needed
MEMORY.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.md
Topic 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 explanations
Memory 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.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/vudovn/ag-kit/memory-system">View memory-system on skillZs</a>