Forem: musecl

The package.json Pattern for AI Agent Memory

musecl — Tue, 17 Feb 2026 14:23:43 +0000

Your agent learned 500 things last month. Then the disk died.

This isn't hypothetical — it happened to me. Months of accumulated corrections, preferences, and domain expertise, gone because I treated agent memory like disposable state instead of valuable data.

The Portability Gap

If you're running AI agents that learn over time, you've probably noticed a gap in the tooling:

Cloud memory APIs — portable, but your agent's knowledge lives on someone else's servers
Local-only systems — private, but one hardware failure away from zero
Protocol-based services — great architecture, but not portable across machines

What I wanted was simple: private, portable, auditable, and free.

A Pattern You Already Know

Every developer intuitively understands this separation:

package.json    → syncs via git
node_modules/   → rebuilds locally from package.json

Agent memory has the same structure:

MEMORY.md       → syncs via git (source of truth)
vectordb/       → rebuilds locally from MEMORY.md (derived artifact)

Source files are human-readable text — Markdown and JSON. They diff cleanly, version naturally, and merge without conflicts. Vector indexes are binary blobs that depend on your local embedding model. They should never touch git.

How It Works

The implementation is a single bash script (~200 lines) that does three things:

Push: Local → Git

Compare workspace files against sync repo by content hash (skip unchanged)
Copy changed .md and .json files
Scan for secrets — abort if API keys found
Commit and push

Pull: Git → Local

git pull --ff-only (fails loudly if diverged — protects local changes)
Copy files to agent workspaces with 600 permissions
Rebuild vector indexes for agents that received changes

Status

Bidirectional drift check — shows files that exist locally but aren't synced, and vice versa.

What Gets Synced (and What Doesn't)

Synced	Not Synced
`*.md` — Memory documents	`*.sqlite` — Vector indexes
`*.json` — Structured data	`vectordb/` — Embedding stores
`.gitignore`	`*.jsonl` — Session transcripts
`sync.sh`	`.key`, `.pem`, `*.env`

The .gitignore does the heavy lifting here. Secrets and binary artifacts stay local. Only human-readable source files travel.

Multi-Agent, Multi-Machine

This pattern scales naturally. Each agent gets its own directory in the repo:

security-auditor/MEMORY.md
growth-engine/MEMORY.md
content-moderator/MEMORY.md

Security knowledge doesn't pollute architecture patterns. And because it's just git, syncing across machines is a push/pull away.

The Secret Scanning Part

The scariest thing about syncing agent memory to git is accidentally pushing API keys. The script runs a regex scan before every commit — looks for common key patterns (sk-, ghp_, Bearer, base64 blobs) and aborts if anything looks suspicious.

Not bulletproof, but it catches the obvious mistakes that would otherwise end up in your git history forever.

Try It

The repo is MIT-licensed: github.com/musecl/musecl-memory

It's a bash script, not a framework. No dependencies beyond git. Works with any agent system that stores memory as files — Claude, GPT, local models, whatever.

If you're running agents that accumulate knowledge, I'm curious: how are you handling persistence today? The tooling landscape is still early, and I think there's a lot of room for different approaches.

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

musecl — Sat, 14 Feb 2026 04:16:11 +0000

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

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)

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

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.

Forem: musecl

The package.json Pattern for AI Agent Memory

The Portability Gap

A Pattern You Already Know

How It Works

Push: Local → Git

Pull: Git → Local

Status

What Gets Synced (and What Doesn't)

Multi-Agent, Multi-Machine

The Secret Scanning Part

Try It

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

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

The Problem

The Solution

Why This Works

How sync.sh Works

Example Use Cases

Getting Started

Compared to Alternatives

When NOT to Use This

Links