DEV Community

musecl
musecl

Posted on

I Built a Zero-Dependency Memory System for AI Agents in 200 Lines of Bash

#ai #agents #bash #opensource

I Built a Zero-Dependency Memory System for AI Agents in 200 Lines of Bash

Most AI agent memory solutions require databases, vector stores, or cloud services. I wanted something simpler.

musecl-memory is a file-based memory sync system for AI agents. No dependencies. No databases. Just bash, git, and markdown.

The Problem

AI agents forget everything between sessions. The standard solutions are:

  • Vector databases (Pinecone, Weaviate, ChromaDB)
  • Cloud memory services (Mem0, Letta)
  • Custom embeddings pipelines

These work, but they're overkill for many use cases. If your agent just needs to remember decisions, preferences, and context across sessions — you don't need a vector DB. You need a file and a sync script.

The Solution

Each agent gets a directory. Each directory has a MEMORY.md file. A single bash script syncs them to a git repo.

agents/
  researcher/MEMORY.md
  coder/MEMORY.md
  reviewer/MEMORY.md
sync.sh
Enter fullscreen mode Exit fullscreen mode

That's it. The MEMORY.md files are plain markdown — agents read them at session start and write findings back. sync.sh handles git add/commit/push with conflict detection.

Why This Works

1. Agents already understand markdown. No serialization, no schema, no ORM. An agent reads a markdown file the same way it reads a prompt.

2. Git gives you versioning for free. Every memory change is a commit. You can diff, revert, branch, and merge memories the same way you manage code.

3. Zero vendor lock-in. Switch LLM providers, agent frameworks, or hosting — your memory files are just text in a git repo.

4. It scales. Whether you have 2 agents or 50, the pattern is the same. Sync takes under 2 seconds.

How sync.sh Works 

# Detect all agent directories
# For each: check if MEMORY.md changed
# Stage changes, commit with timestamp
# Push to remote (handles conflicts with pull --rebase)
Enter fullscreen mode Exit fullscreen mode

Key features:

  • Drift detection: Warns if local and remote diverge
  • Atomic commits: One commit per sync, not per file
  • Conflict-safe: Uses rebase strategy to avoid merge commits
  • Idempotent: Running it twice with no changes is a no-op

Example Use Cases

  • A code review agent that remembers past findings and checks for regressions
  • A research agent that accumulates knowledge across sessions
  • A planning agent that tracks decisions and their rationale
  • A personal assistant that learns preferences over time

Each agent reads its MEMORY.md at the start of every session. No cold starts. Full continuity.

Getting Started 

git clone https://github.com/musecl/musecl-memory.git
cd musecl-memory

# Create an agent
mkdir -p agents/my-agent
cat > agents/my-agent/MEMORY.md << 'EOF'
# My Agent Memory
## Decisions
- Started tracking on 2026-02-13
EOF

# Sync
./sync.sh
Enter fullscreen mode Exit fullscreen mode

Compared to Alternatives

Feature musecl-memory Mem0 Letta Vector DB
Dependencies 0 Python + API Python + DB DB + embeddings
Setup time 30 sec 10+ min 15+ min 20+ min
Cost Free Free tier / paid Free tier / paid Varies
Privacy 100% local Cloud Cloud/local Varies
Versioning Git (built-in) Limited Limited Manual
Framework lock-in None Mem0 SDK Letta SDK DB-specific

When NOT to Use This

  • You need semantic search across thousands of memories → use a vector DB
  • You need real-time memory sharing between concurrent agents → use a database
  • You need sub-document granularity with embeddings → use Mem0 or similar

musecl-memory is for the 80% of cases where agents just need persistent, versioned, human-readable context.

Links

Would love feedback. What's your current approach to agent memory?

Top comments (0)