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:

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

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

# 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

<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

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>

{
  "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>

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

{
  "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>