MemoryAgent

01 — Core Idea

Memory is files.
File management is memory management.

Coding Agents already know how to read, write, edit, and search files. If we persist conversation knowledge as files, they can manage their own memory with zero additional infrastructure.

∅

Zero Infrastructure

No databases, no vector stores, no external services. Memory is plain Markdown files on the file system.

Human-Readable

Every memory is a text file. Users can inspect, edit, or audit the agent's memory at any time with any editor.

Version Controlled

Put it in a Git repo. The full history of memory changes becomes transparent, diffable, and reversible.

∞

Native Capabilities

No new tools needed. Read, Write, Edit, Grep, Glob — the agent's existing toolset is sufficient.

Memory Operation	Agent Tool
Recall	Read / Grep / Glob
Record	Write
Update	Edit
Search	Grep / Glob
Organize	Read + Edit

02 — Architecture

Long-term memory meets
working memory

The agent decides what to load and unload per subtask — like human working memory, loaded on demand and released when done.

Unlimited Capacity

Long-term Memory

File system — all memory files: skills, MCP configs, project context

Agent decides

Limited & Precious

Working Memory

Current context window — only what the active subtask needs

03 — The Skill

Six commands.
One memory file.

The memory-manage skill is a Claude Code Skill that implements Memory as File. Default target: memory.txt — or specify any file.

recall

/memory recall [file]

Read the full contents of the memory file. Summarizes structure first if the file exceeds 200 lines.

record

/memory record <content>

Append a new timestamped entry. Auto-generates a topic label. Never overwrites existing content.

update

/memory update <old> -> <new>

Replace specific content in the memory file. Shows before and after to confirm the change.

/memory search <query>

Search memory for matching content with surrounding context. Suggests alternatives on empty results.

forget

/memory forget <content>

Remove a specific entry from memory, including its timestamp header. Confirms what was removed.

analyze

/memory analyze [file]

Exploratory analysis. Produces a structured report: summary, topics, entities, timeline, gaps, and next steps.

04 — How It Works

From conversation
to persistent knowledge

Conversation happens

You discuss a project with your Coding Agent. Decisions are made, preferences stated, context established.

Knowledge is recorded

The agent appends key information to memory.txt as timestamped entries — either on request or proactively.

Memory is analyzed

Before a new task, the agent runs /memory analyze to build a structured understanding: topics, entities, gaps, next steps.

Context is loaded selectively

The agent (or a sub-agent) loads only the relevant memory for the current subtask — keeping the context window focused and efficient.

Memory evolves

As work progresses, memory is updated, refined, and reorganized. Outdated entries are pruned. The file grows smarter, not just larger.

05 — Validated

Tested on real data.
Not just toy examples.

The skill was validated with both synthetic entries and a real 1,022-line conversation transcript from an actual Claude Code working session.

1,022

Lines of real data

Search matches found

6/6

Commands passed

Analysis sections

What the analysis extracted

Accurate one-paragraph summary of session scope and theme
9 distinct topics identified and ranked by importance
Key entities categorized: people, projects, models, venues, tools
9-step timeline reconstructed from timestamps
Cross-topic relationships and hidden connections discovered
7 knowledge gaps identified with specific questions
7 concrete, actionable next steps suggested
Dual-role conflict (Qwen3-Max as model and evaluator) flagged

06 — Open Questions

What we're still
figuring out

Memory Structure

Store raw transcripts or distilled summaries? Raw is complete but noisy; distilled is concise but loses information.

Granularity

One file per conversation? Split by topic? By timeline? The granularity determines retrieval efficiency.

Semantic Retrieval

Grep is keyword matching. Do we need vector search for semantically similar but differently worded memories? Or is the LLM's comprehension enough?

Lifecycle

How to handle outdated memory? Automatic time-based decay, agent-initiated cleanup, or manual user management?

Active vs. Passive

Should the agent wait for "remember this," or proactively decide which information is worth persisting?

Get Started

Try it now.

Copy the skill into your Claude Code skills directory. Restart your session. Start remembering.

Terminal

# Clone the repository
$ git clone https://github.com/IIIIQIIII/MemoryAgent.git

# Copy the skill to your Claude Code skills directory
$ cp -r MemoryAgent/skills/memory-manage ~/.claude/skills/

# Restart Claude Code, then use it
$ claude

# Record something
> /memory record This project uses TypeScript with bun

# Analyze your memory
> /memory analyze

Memory is files.File management is memory management.