a24z-memory: Your Codebase's Living Memory

One-click install for Cursor & VS Code ↑ • Works with Claude Code, Windsurf, Gemini CLI & Jules

The Problem We Solve

Every codebase accumulates tribal knowledge—those critical insights about why things work the way they do, what pitfalls to avoid, and which patterns to follow. But this knowledge gets lost in:

• 🧠 Developers' heads when they leave or forget
• 💬 Slack threads that disappear into history
• 📝 PR comments that nobody reads again
• 📚 Documentation that becomes stale the moment it's written

Our Solution: Knowledge That Lives With Your Code

a24z-memory captures and preserves your team's hard-won insights by anchoring them directly to your code. Unlike traditional documentation that rots or embeddings that become stale, our knowledge stays fresh because it's connected to the actual files.

When your AI assistant needs context, it doesn't get outdated embeddings—it gets your team's accumulated wisdom plus the current state of your code.

How It Works

🎯 Capture Knowledge Where It Happens

When you discover something important—a tricky bug, a design pattern, an architectural decision—document it instantly:

"Auth middleware breaks with null headers - always validate before parsing"
→ Type: gotcha
→ Tagged as: authentication, middleware, validation
→ Anchored to: src/auth/middleware.ts
→ Stored in: .a24z/notes/ (synced via git)

🔍 Surface Knowledge When You Need It

Your AI assistant automatically accesses this knowledge:

You: "Why does our auth sometimes fail?"
AI: *Searches a24z-memory for auth-related gotchas*
AI: "Found a known issue: Auth middleware breaks with null headers in src/auth/middleware.ts. The team discovered this needs validation before parsing."

🔄 Knowledge That Evolves

As your code changes, the knowledge remains relevant:

• Anchors point to files, not embedded content
• Git tracks changes, showing how understanding evolved
• Types organize knowledge by its nature (decision, pattern, gotcha, explanation)
• Team contributions accumulate over time

The Layered Knowledge Architecture

We use a four-layer stack that keeps knowledge organized, meaningful, current, and shared:

📊 Type Layer    → What kind of knowledge (decision, pattern, gotcha, explanation)
🏷️  Tag Layer     → Semantic categories for discovery
📝 Note Layer    → Your team's insights and explanations
🔗 Anchor Layer  → Live connections to code locations

Plus Git distribution ensures knowledge travels with your code and evolves with your team.

This isn't just storage—it's a living memory system that grows smarter with every insight your team adds.

Real-World Impact

For Individual Developers

• Never lose context when switching between projects
• Learn from past mistakes without repeating them
• Understand "why" not just "what" in unfamiliar code

For Teams

• Onboard faster with accumulated team knowledge
• Share insights automatically through git
• Build institutional memory that survives team changes

For AI Assistants

• Context-aware responses based on real team knowledge
• Avoid known pitfalls documented by your team
• Follow established patterns specific to your codebase

Getting Started

The convenience buttons above handle everything—just click to install. For manual setup or advanced configuration, see the detailed installation guide below.

Learn More

📖 Complete Documentation - Comprehensive guides and API reference
📚 Usage Guide - Quick reference and examples
🔧 Advanced Configuration - Customize for your workflow

Detailed Installation

# Global installation (recommended)
npm install -g a24z-memory

# Or project-specific
npm install a24z-memory --save-dev

# Verify installation
npx a24z-memory --help

# Keep this running in a terminal
npx a24z-memory

# Expected output:
# ✅ a24z-Memory MCP server started successfully
# 📁 MCP Server working directory: /path/to/cwd

{
  "mcpServers": {
    "a24z-memory": {
      "command": "npx",
      "args": ["-y", "a24z-memory"]
    }
  }
}

Advanced Configuration

When working on development tasks, you have access to a a24z-memory MCP server...

### Available Tools

#### discover_a24z_tools - Discover all available tools and capabilities

#### askA24zMemory - Search tribal knowledge and get contextual guidance

#### create_repository_note - Document insights and decisions

#### get_notes - Browse raw notes without AI processing

#### get_repository_tags - Manage note categorization

#### get_repository_types - Get available note types

#### get_repository_guidance - Get repository-specific guidelines

...

### Best Practices

1. Check existing knowledge before starting work
2. Use absolute paths starting with /
3. Document insights after solving problems
4. Read guidance token before creating notes

Troubleshooting

npx a24z-memory
# Should show: "✅ a24z-Memory MCP server started successfully"
# If errors, check Node version: node --version (needs 18+)

pwd  # Get current directory
# Use this path in your commands

git status  # Verify you're in a git repo
git init    # Initialize if needed

DEBUG=a24z-memory:* npx a24z-memory

Quick Demo

1. Install with one click using the buttons above
2. Ask your AI: "What a24z-Memory tools are available?"
3. Start capturing: Document your first insight about your code
4. Experience the difference: Watch your AI leverage accumulated knowledge

Handoff Briefs: Seamless Knowledge Transfer

When transitioning work—whether switching projects, onboarding teammates, or handing off tasks—create a handoff brief that captures everything the next person needs to know:

What Gets Included

• Context & Current State: Where things stand and what's been done
• Code References: Specific files with explanations of their role
• Key Decisions: Why certain approaches were taken
• Next Steps: What needs attention moving forward

How It Works

You: "Create a handoff brief for the auth refactoring"
AI: *Generates comprehensive handoff document*
    - Overview of changes made
    - References to modified files with context
    - Outstanding tasks and considerations
    - Saved to .a24z/handoffs/ for sharing

Your teammate receives a complete picture—not just what changed, but why and what's next. The brief lives in your repository, traveling with the code it describes.

Available Tools

Your AI assistant gains access to powerful knowledge management tools:

• askA24zMemory - Query tribal knowledge with semantic search
• create_repository_note - Document new insights and decisions
• get_notes - Browse existing knowledge
• get_repository_tags - Get available tags for categorization
• get_repository_types - Get available note types
• get_repository_guidance - Access team guidelines
• get_repository_note - Retrieve specific note by ID
• delete_repository_note - Remove outdated notes
• create_handoff_brief - Generate handoff documentation
• discover_a24z_tools - Explore all capabilities

Why This Is Different

Programmatic Usage

import { run } from 'a24z-memory';
run();

Contributing

We welcome contributions! See our contribution guidelines for details.

License

MIT License - see LICENSE for details.

Support

• 📧 Email Support
• 🐛 Report Issues
• 💬 Join Discord

Built with ❤️ by the a24z team to make every codebase smarter.