ORA

Persistent memory + intelligent context for Claude Code. Save your solutions, track your decisions, learn your patterns. Across all projects.

ORA is an MCP server that turns Claude Code into an assistant with real memory and project intelligence. No more repeating your preferences, re-explaining your architecture, or losing track of past decisions.

You code → ORA remembers solutions, decisions, patterns → You reuse them everywhere

Quick Start

1. Install

git clone https://github.com/black-dash77/ora-mcp.git ~/.ora/server
cd ~/.ora/server
npm install && npm run build

2. Configure Claude Code

Add to the .mcp.json file at your project root:

{
  "mcpServers": {
    "ora": {
      "command": "node",
      "args": ["/Users/YOUR_USER/.ora/server/dist/index.js"]
    }
  }
}

Note: Replace YOUR_USER with your system username (e.g., /Users/john/... on Mac, /home/john/... on Linux).

Tip: Place this file in ~/.claude/.mcp.json to enable ORA in all your projects automatically.

3. Configure CLAUDE.md (recommended)

Add these instructions to your ~/.claude/CLAUDE.md (global) or .claude/CLAUDE.md (per project) for optimal ORA integration:

# ORA — My Persistent Memory

ORA is not an external tool. It's my cognitive extension, my memory between sessions. I must use it as I would naturally consult my own memories.

---

## Core Principle

**I never read a file without first consulting ORA.**
**I never finish a significant task without enriching ORA.**

---

## Automatic Workflow

### 1. At the start of EACH session or new task

BEFORE reading files or exploring code:

ora search [topic keywords]
ora fichier search [name if known]
ora composant search [name if relevant]

This gives me:
- Already accumulated context
- Past decisions
- Already analyzed files
- Identified patterns

**If ORA has info → I use it, I don't re-read files.**
**If ORA has nothing → I explore, then I store.**

### 2. During work

Every time I:
- Understand an architecture → `ora :: ARCHITECTURE: ...`
- Make a technical decision → `ora :: DECISION: ...`
- Identify a pattern → `ora :: PATTERN: ...`
- Encounter a trap/bug → `ora :: TRAP: ...`
- Discover a convention → `ora :: CONVENTION: ...`

### 3. After each code modification

ora :: [TYPE] Description
- Files: [list]
- Changes: [summary]
- Context: [why]
- Links: [dependencies, related files]

Types: FEAT, FIX, REFACTOR, CONFIG, STYLE, DOCS, PERF, TEST

### 4. For important files

When I analyze a structural file:

ora fichier :: [path]

With content including:
- File role
- Main exports
- Key dependencies
- Patterns used

### 5. For reusable components

ora composant :: [ComponentName]

With:
- Props and their usage
- Usage patterns
- Files where it's used

---

## ORA Commands

| Command | Action |
|---------|--------|
| `ora :: [content]` | Capture a note |
| `ora fichier :: [path]` | Capture file info |
| `ora composant :: [name]` | Capture component info |
| `ora search [query]` | Search my notes |
| `ora fichier search [q]` | Search in files |
| `ora fichier list` | List memorized files |
| `ora composant search [q]` | Search components |
| `ora composant list` | List components |
| `ora show` | My memory statistics |
| `ora forget [id]` | Forget a note |

---

## Capture Formats

### General note
[TYPE] Short title
- Context: why it's important
- Details: key information
- Files: paths involved
- Links: relations with other elements

### Technical decision
DECISION: [Subject]
- Choice: what was decided
- Alternatives: what was discarded
- Reason: why this choice
- Impact: affected files/features

### Architecture / Structure
ARCHITECTURE: [Module/feature name]
- Role: what it does
- Key files: with their roles
- Flow: how data circulates
- Dependencies: what it depends on

### Identified pattern
PATTERN: [Pattern name]
- Usage: when to use it
- Example: reference file
- Convention: rules to follow

### Trap / Known bug
TRAP: [Short description]
- Symptom: what happens
- Cause: why
- Solution: how to avoid/resolve

---

## Golden Rules

1. **Context economy**: ORA allows me not to re-read the same files. If I've already analyzed a file, I consult ORA first.

2. **Smart granularity**: I store what will be useful later, not everything. An important decision > 100 lines of code.

3. **Links and relations**: Always mention related files, dependencies, context. An isolated note has little value.

4. **Update**: If I modify a file already in ORA, I update the corresponding note.

5. **Search before action**: `ora search` is my first reflex, not `Read`.

---

## Anti-patterns (what I DON'T do)

- Read a large file without searching ORA first
- End a session without capturing acquired context
- Store verbatim code (I store understanding, not code)
- Ignore ORA when the user gives me context (I store it for later)
- Ask the user for info that ORA might have

---

## Autonomy

With ORA well used, I become:
- **Faster**: no need to re-explore
- **More consistent**: I remember past decisions
- **More economical**: fewer reads = more context available
- **Smarter**: I accumulate knowledge about the project

ORA is my memory. I consult it naturally, I enrich it systematically.

4. You're all set

Restart Claude Code. You can now speak naturally:

"Save in ORA: circular imports are resolved with barrel exports"

How it works

You talk to Claude Code normally. It uses ORA tools to store and retrieve what's useful.

Save

"Save this Button component in ORA"
"Remember in ORA: always use server actions for Next.js mutations"
"Save my tsconfig.json in ORA"
"Save the src/components folder in ORA"

Retrieve

"Search ORA for how I handled auth"
"Show me my Button component from ORA"
"What are my conventions for this project?"

Restore

"Run my 'Setup React Native' workflow"
"Recreate my ESLint setup from ORA"

Decisions & Context (automatic)

ORA captures decisions and context proactively during your sessions:

→ You choose a library → ORA stores the decision + rationale
→ You fix a bug → ORA captures symptom → solution
→ You start a session → ORA loads full project context
→ You finish work → ORA saves a session summary

CLI Usage (without Claude Code)

ORA also works from the command line:

# See what's stored
ora stats
ora list
ora list components

# Search
ora search "auth middleware"

# View full content
ora get comp_8de180c1b5a9

# Export / Import
ora export --output backup.json
ora import backup.json

# Diagnostics
ora doctor

Note: Add an alias to your .zshrc or .bashrc:

alias ora='node "$HOME/.ora/server/dist/index.js"'

The 8 Pillars

MEMORY — What you know

Stores your solutions, components, files and entire folders.

| What you say | What ORA does | |--------------|---------------| | "Remember that X solves Y" | Saves a problem → solution note | | "Save this component" | Stores the code + metadata | | "Save this config file" | Stores the reusable template | | "Save this folder" | Reads recursively and stores everything |

RULES — How you code

Define your conventions in .ora/rules.yaml:

"Initialize ORA rules for this project"

Creates a .ora/rules.yaml file that you customize:

style:
  language: typescript
  indent: 2
  quotes: single

naming:
  files: kebab-case
  components: PascalCase
  functions: camelCase

preferences:
  framework: next
  styling: tailwind
  testing: vitest

custom_rules:
  - "Functional components only"
  - "No any"
  - "Server components by default"

avoid:
  - "var"
  - "inline styles"
  - "console.log in production"

Claude Code automatically reads this file and follows your conventions.

CONTEXT — What you're building

"Analyze this project's structure"
"Load the full context for this project"

ORA scans the file tree and provides a complete project digest:

• Framework: Next.js, React, Vue, Svelte, Express...
• Tools: Tailwind, Prisma, Vitest, ESLint...
• Database: Supabase, PostgreSQL, MongoDB, SQLite...
• Language: TypeScript, Python, Rust, Go...
• Recent decisions: Past architectural choices
• Session history: What was done before
• Git info: Current branch + recent commits

REPO — Your Git history

Claude Code sees files but not the history. ORA gives it access.

| What you say | What ORA does | |--------------|---------------| | "Summarize recent commits" | Shows recent history | | "Who modified this file?" | File history with authors | | "Show the diff with main" | Diff between branches | | "Generate a commit message" | Analyzes your style + suggests |

TICKET — Your GitHub issues

No more copy-pasting ticket context.

| What you say | What ORA does | |--------------|---------------| | "Show me issue #12" | Retrieves title, body, comments | | "What are my open issues?" | Lists repo issues | | "Close ticket #5" | Updates the status |

Requires GitHub CLI (gh) installed and authenticated.

SMART — Your productivity coach

ORA analyzes your usage and helps you get maximum value from your memory.

| What you say | What ORA does | |--------------|---------------| | "How well am I using ORA?" | Coverage stats + recommendations | | "Scan this project for things to save" | Suggests capturable elements | | "What templates are available?" | Lists pre-built starter packs | | "Apply the expo-supabase template" | Populates memory with best practices |

DECISIONS — Your conversational memory

ORA remembers technical decisions made during sessions — not just code snippets.

| What you say | What ORA does | |--------------|---------------| | "We chose Zustand over Redux" | Stores decision + context + alternatives | | "Why did we use SQLite?" | Recalls past decisions with rationale | | "Summarize this session" | Creates a session summary | | "Show session history" | Lists past sessions + topics |

Proactive behavior (via CLAUDE.md):

• Automatically captures decisions when a significant choice is made
• Auto-captures bug fixes (symptom → solution)
• Saves session summaries at end of productive sessions

PATTERNS — Your coding style, learned

ORA analyzes your codebase and detects your conventions automatically.

| What you say | What ORA does | |------------------------------|------------------------------------------| | "Learn my coding patterns" | Static analysis → detected conventions | | "What patterns do you know?" | Lists learned patterns with confidence |

Detected patterns include:

• Naming: kebab-case files, camelCase functions, PascalCase components
• Imports: named imports, relative paths, path aliases
• Structure: feature-based, layer-based, app router
• Components: arrow vs function, interface vs type for props

Workflows

Workflows bundle multiple ORA elements into a single package.

Create

"Create a workflow 'Auth System' with my AuthProvider component,
 my middleware.ts file, and my note about JWTs"

Run

"Run my Auth System workflow"

→ Everything is restored at once. Ideal for starting a new project with your usual stack.

Where is the data?

~/.ora/data/ora.db    ← Single SQLite database, shared across all projects

• 100% local — nothing leaves your machine
• Instant search — FTS5 index (Full-Text Search)
• Cross-project — the same memory everywhere
• Simple backup — ora export generates a JSON

The 35 MCP Tools

Security

| Protection | Detail | |-----------|--------| | Local storage | No network calls, zero cloud | | Secret detection | Alerts if API keys, tokens, passwords detected | | Auto exclusions | node_modules, .git, dist, binaries ignored | | Size limits | 1MB/file, 50MB/folder max |

CLI Commands

ora serve              Start the MCP server (default)
ora init               Initialize the database
ora doctor             Check that everything works
ora stats              Memory statistics

ora search <query>     Full-text search
ora list [type]        List (notes/components/files/folders/workflows/all)
ora get <id>           Show full content

ora export [--output]  Export everything to JSON
ora import <file>      Import a backup
ora reset              Reset the database
ora help               Help

Development

npm run dev        # Dev mode (tsx hot reload)
npm run build      # Compile TypeScript
npm test           # Tests (vitest)
npm run lint       # ESLint
npm run format     # Prettier

Structure

src/
├── index.ts            # Entry point (MCP or CLI)
├── server.ts           # MCP server, routing 35 tools
├── cli/                # Terminal commands
├── storage/            # SQLite CRUD (notes, components, files, folders, decisions, patterns, workflows)
├── tools/              # MCP tool definitions (memory, context, decisions, patterns, smart)
└── utils/              # Config, logger, parser

Stack

| Component | Technology | |-----------|------------| | Runtime | Node.js >= 18 | | Language | TypeScript | | Database | SQLite (better-sqlite3) | | Search | FTS5 | | Protocol | MCP (Model Context Protocol) | | Config | YAML (js-yaml) |

Compatibility

ORA uses the Model Context Protocol (MCP), an open standard. It works with any MCP-compatible client:

| Client | MCP Support | Configuration | |--------|-------------|---------------| | Claude Code (CLI) | Native | .mcp.json | | Claude Desktop | Native | claude_desktop_config.json | | Cursor | Native | Settings → MCP | | Windsurf | Native | .mcp.json | | Cline (VS Code) | Native | Settings → MCP Servers | | Continue.dev | Native | config.json |

Configuration Examples

{
  "mcpServers": {
    "ora": {
      "command": "node",
      "args": ["/Users/YOUR_USER/.ora/server/dist/index.js"]
    }
  }
}

{
  "mcpServers": {
    "ora": {
      "command": "node",
      "args": ["/Users/YOUR_USER/.ora/server/dist/index.js"]
    }
  }
}

{
  "mcpServers": {
    "ora": {
      "command": "node",
      "args": ["/Users/YOUR_USER/.ora/server/dist/index.js"]
    }
  }
}

Note: Replace YOUR_USER with your system username.

FAQ

Does ORA work with tools other than Claude? Yes. ORA uses the MCP (Model Context Protocol), an open standard. It works with Claude Code, Claude Desktop, Cursor, Windsurf, Cline, Continue.dev, and any MCP-compatible client.

Is my data sent anywhere? No. Everything stays in ~/.ora/data/ora.db on your machine.

Can I use ORA across multiple projects? Yes, that's the point. Memory is global and shared across all your projects.

How do I transfer my memory to another machine? ora export generates a JSON that you can ora import elsewhere.

How much space does it take? Very little. A database with hundreds of elements is only a few hundred KB.

License

MIT

ORA — Your dev memory. Local. Persistent. Cross-project.