Shared Project Memory: Your AI Agent That Remembers Across Sessions

AI coding agents start fresh every time you launch them. You explain your project structure, your conventions, your API endpoints, again and again. It's like having a coworker with perfect recall who somehow forgets everything overnight.

That's why project memory matters. Your agent should remember that you prefer userId over user_id, that the test database runs on port 5433, or that you're migrating from Express to Fastify. These aren't one-off details. They're context that should persist.

What Shared Project Memory Looks Like

muxd has two memory tools built in: memory_read and memory_write. They store key-value facts in a simple JSON file at .muxd/memory.json in your project directory. The agent reads these facts automatically at the start of each session, giving it immediate context about your project.

Here is what your memory file might contain:

{
  "facts": {
    "database_url": "postgresql://localhost:5433/test",
    "code_style": "camelCase for vars, PascalCase for types",
    "auth_method": "JWT with refresh tokens"
  }
}

No prompts to craft. No files to manually edit. Just tell the agent "remember we use camelCase" and it's stored for next time.

Local vs. Shared: A Simple Choice

Not all memories should sync everywhere. API keys, machine-specific paths, local ports — these stay on your machine. Mark them scope: local and they never leave your device.

Shared facts (scope: shared by default) sync to the muxd hub when you're connected. Switch from your laptop to your desktop and your project context comes with you. The hub merges changes intelligently: local keys are never overwritten, and the most recent shared value wins.

Local scope is for:

  • API keys and secrets
  • Local dev ports and file paths
  • Machine-specific environment variables

Shared scope is for:

  • Coding conventions (code_style: camelCase)
  • API preferences and architecture decisions
  • Project patterns that everyone should know

Why This Beats Prompt Engineering

You could dump all this into a CLAUDE.md or .cursorrules file. Many teams do. But those files get stale, they're easy to forget, and they require discipline to maintain.

Project memory is different:

  • It's conversational. Just say "remember we use Zod for validation" during a session. No file editing required.
  • It's alive. The agent can update its own memory when it learns new conventions from your code.
  • It's portable. Switch machines, and your context follows if you want it to.

How It Works Under the Hood

The memory system is deliberately simple. A memoryFile struct holds facts and a list of local-only keys. Writes are atomic — temp file then rename — so corruption is impossible even if the process crashes mid-save.

type memoryFile struct {
    Facts     map[string]string `json:"facts"`
    LocalKeys []string          `json:"local_keys,omitempty"`
}

Thread-safe with a mutex. Sorted output for consistent prompts. The whole implementation is under 400 lines, including tests.

When the hub is connected, shared facts push automatically. The merge logic is straightforward: shared keys from the hub overwrite local shared keys, local-only keys are sacred. No complex conflict resolution. No surprises.

Real-World Usage

Here are patterns that actually get stored:

  • Project conventions: "We use SvelteKit, not Next.js"
  • Environment details: "Dev server runs on 3001, not 3000"
  • API preferences: "Use the new /v2/ endpoints, legacy is deprecated"
  • Personal style: "I prefer early returns over nested ifs"
  • Secrets (local only): "AWS_PROFILE=muxd-dev"

The agent references these automatically. No prompt injection tricks. No context window pressure from repeating the same facts.

Getting Started

Project memory works out of the box. Start a muxd session and say something like:

Remember that we use TypeScript strict mode and prefer interface over type for object shapes.

The agent stores it. Next session, it knows.

Read the full project memory documentation for details on local vs. shared scope, hub sync, and best practices for organizing your facts.

The Bottom Line

An AI agent without memory is a goldfish with a compiler. Every session starts from zero, repeating context that should have been learned long ago. Project memory fixes that — simple storage, automatic sync, and the context you need when you need it.

Your agent should remember what matters. Now it does.