# ORA

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

ORA is an [MCP](https://modelcontextprotocol.io) 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

```bash
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:

```json
{
  "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:

<details>
<summary><strong>Click to expand CLAUDE.md instructions</strong></summary>

```markdown
# 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.
```

</details>

### 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:

```bash
# 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`:
> ```bash
> 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:

```yaml
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](https://cli.github.com) (`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

<details>
<summary><strong>MEMORY</strong> (9 tools)</summary>

| Tool | Role |
|------|------|
| `ora_capture_note` | Store a solution (problem → solution) |
| `ora_capture_component` | Store a component with its code |
| `ora_capture_file` | Store a template file |
| `ora_capture_folder` | Store an entire folder |
| `ora_get` | Retrieve full content by ID |
| `ora_search` | Global full-text search |
| `ora_list` | List by type |
| `ora_delete` | Delete an element |
| `ora_stats` | Memory stats |

</details>

<details>
<summary><strong>RULES</strong> (2 tools)</summary>

| Tool | Role |
|------|------|
| `ora_get_rules` | Read project conventions |
| `ora_init_rules` | Create the .ora/rules.yaml template |

</details>

<details>
<summary><strong>CONTEXT</strong> (2 tools)</summary>

| Tool                  | Role                                                     |
|-----------------------|----------------------------------------------------------|
| `ora_get_structure`   | Analyze file tree + detect stack                         |
| `ora_project_context` | Full project digest (structure, decisions, sessions, git) |

</details>

<details>
<summary><strong>WORKFLOWS</strong> (4 tools)</summary>

| Tool | Role |
|------|------|
| `ora_create_workflow` | Create a bundle |
| `ora_run_workflow` | Execute (restore everything) |
| `ora_list_workflows` | List workflows |
| `ora_delete_workflow` | Delete a workflow |

</details>

<details>
<summary><strong>REPO</strong> (4 tools)</summary>

| Tool | Role |
|------|------|
| `ora_git_summary` | Summarize recent commits |
| `ora_git_file_history` | File history (who, when, why) |
| `ora_git_diff` | Diff between branches or commits |
| `ora_git_commit_style` | Analyze style + suggest a message |

</details>

<details>
<summary><strong>TICKET</strong> (3 tools)</summary>

| Tool | Role |
|------|------|
| `ora_ticket_get` | Retrieve a full GitHub ticket |
| `ora_ticket_list` | List issues (filter by status/labels) |
| `ora_ticket_update` | Close/reopen + comment |

</details>

<details>
<summary><strong>SMART</strong> (4 tools)</summary>

| Tool | Role |
|------|------|
| `ora_coverage` | Memory usage stats + recommendations |
| `ora_suggest` | Scan a project and suggest what to capture |
| `ora_templates` | List available template packs |
| `ora_apply_template` | Apply a template to populate memory |

</details>

<details>
<summary><strong>DECISIONS</strong> (5 tools)</summary>

| Tool | Role |
|------|------|
| `ora_capture_decision` | Store a technical decision with context |
| `ora_recall_decisions` | Search past decisions (FTS) |
| `ora_session_summary` | Create a session summary |
| `ora_session_history` | List past sessions |
| `ora_auto_capture` | Smart multi-type capture (bug_fix, decision, pattern, tip) |

</details>

<details>
<summary><strong>PATTERNS</strong> (2 tools)</summary>

| Tool                 | Role                                 |
|----------------------|--------------------------------------|
| `ora_learn_patterns` | Analyze code and detect conventions  |
| `ora_check_patterns` | List learned patterns for a project  |

</details>

---

## 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

```bash
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

<details>
<summary><strong>Claude Code / Windsurf</strong> (.mcp.json at project root)</summary>

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

</details>

<details>
<summary><strong>Claude Desktop</strong> (~/Library/Application Support/Claude/claude_desktop_config.json)</summary>

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

</details>

<details>
<summary><strong>Cursor</strong> (Settings → Features → MCP Servers)</summary>

Add an MCP server with:
- **Command**: `node`
- **Args**: `/Users/YOUR_USER/.ora/server/dist/index.js`

Or in `.cursor/mcp.json`:

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

</details>

> **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

---

<p align="center">
  <strong>ORA</strong> — Your dev memory. Local. Persistent. Cross-project.
</p>