agentleFS
soumatheusgomessoumatheusgomes/agentville/.claude/skills/memory-system/SKILL.md

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

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
  1. Distinctive:

    Check if relevant topic file exists

    line 127
  2. Distinctive:

    If yes → append to existing topic file

    line 128
  3. Distinctive:

    If no → create new topic file with frontmatter

    line 129
  4. Distinctive:

    Update MEMORY.md index with one-line pointer

    line 130
  5. Distinctive:

    If match found → read the referenced topic file

    line 137
  6. Distinctive:

    Never auto-delete — always ask user first

    line 151

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md
<!-- 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 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

TypeWhat to StoreExample
userRole, preferences, tools, communication style"Senior DevOps, prefers dark mode"
feedbackWhat user liked/disliked about agent output"User said 'too verbose', prefers tables"
projectCoding standards, tech choices, conventions"Use bun not npm, Tailwind v4"
referenceNon-sensitive infrastructure notes, public URLs, configs"Prod API hostname and port"

What NOT to Save

Don't SaveWhy
Secrets, credentials, tokens, passwords, private keys, or API keysMemory is persistent and may be shared across sessions
Information derivable from codeRead package.json instead of memorizing deps
Temporary debug contextClutters memory, not useful later
Exact code snippetsCode changes — memory becomes stale
File paths that may moveUse glob patterns or descriptions instead
Entire conversation transcriptsMemory is for distilled insights only

Operations

Save (Trigger: user says "remember", "save", "don't forget")

  1. Identify the information type (user/feedback/project/reference)
  2. Check if relevant topic file exists
  3. If yes → append to existing topic file
  4. If no → create new topic file with frontmatter
  5. Update MEMORY.md index with one-line pointer
  6. Confirm to user: "Saved to memory: [summary]"

Recall (Trigger: session start, or "what do you remember about X")

  1. Read .agents/memory/MEMORY.md index
  2. Scan for relevant entries matching the current task
  3. If match found → read the referenced topic file
  4. Apply recalled context silently (don't recite memories unless asked)

Search (Trigger: "do I have any notes about X")

  1. Grep across .agents/memory/*.md for the search term
  2. Return matching entries with file references
  3. Offer to read full topic file if user wants details

Prune (Trigger: index exceeds 200 lines)

  1. Warn: "Memory index is getting large (X lines). Review recommended."
  2. Suggest merging related entries
  3. Suggest archiving old entries to memory/archive/
  4. 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

ArtifactPurposeLifespanLocation
MemoryCross-session knowledgePermanent until pruned.agents/memory/
PlanTask breakdown for current projectUntil project completeProject root
TaskProgress tracker for current sessionUntil session endsArtifact directory

Memory = what you KNOW. Plan = what you'll DO. Task = what you're DOING NOW.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.