Contributing

Help make Memoria better. Contributions of all kinds are welcome.

Ways to Contribute

• Report bugs — Found an issue? Open a GitHub issue
• Suggest features — Have an idea? Start a discussion
• Improve docs — Fix typos, add examples, clarify explanations
• Submit code — Fix bugs or implement new features
• Share feedback — Tell us how you use Memoria

Development Setup

Prerequisites

• Node.js 18 or higher
• npm or yarn
• Git

Clone and Install

# Clone the repository
git clone https://github.com/byronwade/memoria.git
cd memoria

# Install dependencies
npm install

# Build the project
npm run build

Project Structure

memoria/
├── src/
│   ├── index.ts          # MCP server entry point
│   ├── cli.ts            # CLI commands
│   ├── engines/          # Analysis engines
│   │   ├── volatility.ts
│   │   ├── entanglement.ts
│   │   ├── sentinel.ts
│   │   └── static-import.ts
│   ├── tools/            # MCP tool definitions
│   │   ├── analyze-file.ts
│   │   └── ask-history.ts
│   └── utils/            # Shared utilities
├── tests/                # Test files
├── package.json
└── tsconfig.json

Running Locally

# Run in development mode (auto-reload)
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Build for production
npm run build

# Run the built version
npm start

Testing with AI Tools

To test your changes with an AI tool:

# Build first
npm run build

# Update your MCP config to use local version
{
  "mcpServers": {
    "memoria": {
      "command": "node",
      "args": ["/path/to/memoria/dist/index.js"]
    }
  }
}

# Restart your AI tool to pick up changes

Code Style

We use ESLint and Prettier to maintain consistent code style:

# Check for linting errors
npm run lint

# Fix auto-fixable issues
npm run lint:fix

# Format code
npm run format

Guidelines

• Use TypeScript for all new code
• Write descriptive variable and function names
• Add JSDoc comments for public APIs
• Keep functions focused and small
• Prefer composition over inheritance

Pull Request Process

1. Fork the repository and create your branch from main
2. Make your changes with clear, atomic commits
3. Add tests for new features or bug fixes
4. Update documentation if needed
5. Run the test suite and ensure all tests pass
6. Submit a pull request with a clear description

Commit Messages

We follow conventional commits:

feat: add new analysis engine for import cycles
fix: handle empty git history gracefully
docs: update installation guide for Windows
refactor: simplify cache implementation
test: add tests for volatility engine
chore: update dependencies

PR Description Template

## What does this PR do?
Brief description of the changes.

## Why is this change needed?
Context and motivation for the change.

## How has this been tested?
Describe how you tested your changes.

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Lint and format pass
- [ ] All tests pass

Architecture Overview

Analysis Engines

Each engine is responsible for a specific type of analysis:

Data Flow

User Request
    ↓
MCP Tool (analyze_file / ask_history)
    ↓
Engine Coordinator
    ↓
┌─────────────────────────────────────┐
│  Volatility → Entanglement → ...    │
│     (parallel execution)            │
└─────────────────────────────────────┘
    ↓
Result Formatter
    ↓
Cached Response to AI

Adding a New Engine

To add a new analysis engine:

1. Create a new file in src/engines/
2. Implement the engine interface
3. Register it in the coordinator
4. Add configuration options
5. Write tests
6. Update documentation

// src/engines/my-engine.ts
export interface MyEngineResult {
  // Define your output structure
}

export async function runMyEngine(
  file: string,
  config: Config
): Promise<MyEngineResult> {
  // Implementation
}

Getting Help

• GitHub Issues — Report bugs or request features
• Discussions — Ask questions or share ideas

License

By contributing to Memoria, you agree that your contributions will be licensed under the MIT License.