Membase: Git-Native Project Memory

TL;DR: Store project decisions with

scripts/mb add

, retrieve with

scripts/mb query

, maintain consistency across sessions.

Membase is a git-native project memory system that stores project knowledge in simple text files (

.membase/

). It uses multi-dimensional tagging (topic + phase) to organize information and enables efficient context retrieval across sessions.

Core principle: Store decisions and context so they're never lost between sessions. Query before implementing to avoid contradicting earlier decisions.

Quick Start

# Initialize membase
scripts/mb init

# Add a topic for your project
scripts/mb dims add topic authentication

# Store a decision
scripts/mb add \
  -s "JWT auth with 24h expiry" \
  -c "Using JWT for stateless authentication. Tokens expire in 24h. Refresh tokens valid 7 days." \
  topic=authentication phase=decision

# Query before implementing
scripts/mb query --topic authentication --phase decision

When to Use Membase

Store memories when:

• Design decisions are made (architecture, technology choices, patterns)
• Implementation approaches are chosen (algorithms, data structures)
• Gotchas are discovered (edge cases, framework quirks, workarounds)
• User states preferences (requirements, coding style)
• Key patterns are established (file locations, naming conventions)

Retrieve memories when:

• Starting work on a topic (check existing decisions first)
• User asks about previous decisions ("What did we decide about X?")
• Implementing with potential context (maintain consistency)
• Debugging or troubleshooting (check for known issues)

Multi-Dimensional Tagging

Organize memories with two dimensions:

topic - Project-specific areas you define:

scripts/mb dims add topic authentication
scripts/mb dims add topic database
scripts/mb dims add topic api

phase - Workflow stage (pre-populated):

• decision

  - Architectural/design decisions ⭐ Most important

• backend-implementation

  - Backend code details

• frontend-implementation

  - Frontend code details

• troubleshooting

  - Known issues and solutions

• planning

  ,

  requirements

  ,

  testing

  ,

  documentation

  ,

  deployment

Common Patterns

Record a decision:

scripts/mb add \
  -s "PostgreSQL for main database" \
  -c "Chose PostgreSQL over MySQL for JSON support. Using SQLAlchemy ORM." \
  topic=database phase=decision

Query before implementing:

scripts/mb query --topic database --phase decision
scripts/mb query --search "PostgreSQL"

Document implementation:

scripts/mb add \
  -s "User model in src/models/user.py" \
  -c "Fields: username, email, password_hash. Email is unique. Bcrypt with 12 rounds." \
  topic=authentication phase=backend-implementation

Capture gotchas:

scripts/mb add \
  -s "Redis rate limiting memory leak fix" \
  -c "IMPORTANT: Must call redis.expire() after incrementing counter to prevent leak." \
  topic=api phase=troubleshooting

Best Practices

Writing summaries (≤100 chars):

• ✓ Specific: "JWT auth with 24h expiry and refresh tokens"
• ✗ Vague: "Authentication stuff"

Writing content:

• Include the "why" behind decisions
• Mention file paths and locations
• Note alternatives considered
• Add specific configuration values

Tagging consistently:

topic=authentication phase=decision         # Design decision
topic=authentication phase=backend-implementation  # Implementation
topic=authentication phase=troubleshooting  # Problem/solution

Claude Code Integration

For Claude: Proactively use membase by:

1. Query before implementing - Check

   scripts/mb query --topic <area> --phase decision

2. Store after deciding - Suggest storing significant decisions
3. Maintain consistency - Reference stored decisions (mention memory ID)
4. Update when needed - Suggest edits if decisions change

Example workflow:

User: "Let's add user authentication"
Claude: "Let me check existing decisions..."
[Runs: scripts/mb query --topic authentication --phase decision]
Claude: "Found JWT auth decision (memory abc12345). I'll follow that pattern..."

Essential Commands

# Initialize
scripts/mb init

# Add memory
scripts/mb add -s "summary" -c "content" topic=X phase=Y

# Query
scripts/mb query --topic X --phase Y
scripts/mb query --search "keyword"
scripts/mb query --id abc123
scripts/mb query --all

# Manage dimensions
scripts/mb dims                    # List all
scripts/mb dims add topic <name>   # Add topic value

# Stats
scripts/mb stats

Advanced Usage

For detailed examples, advanced commands, workflow integration, and tips, see REFERENCE.md.

---

Remember: Query before implementing, store after deciding. Membase keeps context alive across sessions.