<p align="center">
  <a href="https://ouso.ai">
    <img src="./assets/ouso-logo.png" alt="Ouso" width="220" />
  </a>
</p>

<h3 align="center">Ouso Code</h3>
<p align="center">
  <strong>Your coding agent finally remembers.</strong><br />
  Persistent, local, cross-editor memory over MCP — capture a decision once,
  recall it in Cursor, Claude Code, Codex, or Windsurf, across every session.
</p>

<p align="center">
  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js-%3E%3D20-339933?style=for-the-badge&logo=nodedotjs&logoColor=white" alt="Node 20+" /></a>
  <img src="https://img.shields.io/badge/100%25_local-no_API_key-2E7D32?style=for-the-badge" alt="Local-first" />
  <img src="https://img.shields.io/badge/MCP-Cursor·Claude·Codex·Windsurf-4453A6?style=for-the-badge" alt="MCP" />
  <img src="https://img.shields.io/badge/benchmarks-reproducible-C49A3C?style=for-the-badge&labelColor=0C1829" alt="Reproducible benchmarks" />
  <a href="./LICENSE.md"><img src="https://img.shields.io/badge/license-source--available-C47A00?style=for-the-badge" alt="Source-available license" /></a>
</p>

<p align="center">
  <a href="#install">Install</a> · <a href="#connect-your-ide">Connect IDE</a> · <a href="#the-rhythm">How to use</a> · <a href="#model-routing">Model routing</a> · <a href="#reproducible-evaluation">Evaluation</a> · <a href="#upgrade-to-hosted-ouso-recall">Upgrade</a> · <a href="./LICENSE.md">License</a>
</p>

---

> [!IMPORTANT]
> Ouso Code is **source-available**, not OSI-licensed open source. Personal, internal-company,
> evaluation, and local integration use are allowed; hosted competing services and commercial
> redistribution require permission. See [LICENSE.md](./LICENSE.md).

Every new chat, your coding agent forgets why you chose Postgres, what fixed last month's OOM, and the
convention you agreed on yesterday — so you re-explain your own codebase, again. **Ouso Code** gives it a
memory that **persists across sessions and editors**, over **MCP**, running **100% on your machine**: your
own SQLite file, your own model. No account. No API key. Nothing leaves your laptop.

## Why you'll actually use it

- 🏠 **Truly local.** Your SQLite, your model — local [Ollama](https://ollama.com) by default, or any
  OpenAI / Azure endpoint. Zero data leaves your machine unless *you* point it at a cloud model.
- 🧩 **One memory, every editor.** Cursor, Claude Code, Codex, Windsurf, Claude Desktop — capture in one,
  recall in all. One file. One brain. `caller` records which editor wrote each memory.
- ⚡ **60-second setup.** `npm run setup` writes ready-to-paste configs for all five editors, with your
  paths already filled in. No sign-up, no key.
- 💸 **Use the quota you already have.** Let frontier models plan and review, while cheaper models handle
  small edits, tests, docs, and narrow subagent work from the same shared memory.
- 🎯 **Code-aware, not prose-aware.** It splits identifiers the way you read them — `useAuth` vs
  `useUser`, error `E1042` vs `E1043` — so near-identical symbols don't blur together.
- 🔬 **Provable, not marketing.** Every benchmark below runs on *your* machine in one command. No vendor
  numbers you can't check.

## Install

Works on Windows, macOS, and Linux. **No API key needed** with local [Ollama](https://ollama.com):

```bash
ollama pull nomic-embed-text   # default local embedder
```

Windows PowerShell:

```powershell
git clone https://github.com/Ouso-ai/Ouso-Code.git
cd Ouso-Code
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1
```

macOS / Linux:

```bash
git clone https://github.com/Ouso-ai/Ouso-Code.git
cd Ouso-Code
bash scripts/install.sh
```

Manual path for any OS:

```bash
npm install
npm run setup
```

`npm run setup` creates `.env`, migrates your local SQLite DB, and writes ready-to-paste MCP configs
with this machine's absolute paths. Full cross-platform guide: [`docs/INSTALL.md`](./docs/INSTALL.md).

## Connect your IDE

| IDE | Where the generated config goes |
|:--|:--|
| **Cursor** | `examples/generated/cursor-mcp.json` → project `.cursor/mcp.json` or `~/.cursor/mcp.json` |
| **Claude Desktop** | `examples/generated/claude-desktop-mcp.json` → macOS `~/Library/Application Support/Claude/claude_desktop_config.json` · Windows `%APPDATA%\Claude\claude_desktop_config.json` · Linux `~/.config/Claude/claude_desktop_config.json` |
| **Windsurf** | `examples/generated/windsurf-mcp.json` → `~/.codeium/windsurf/mcp_config.json` |
| **Codex** | `examples/generated/codex-config.toml` block → `~/.codex/config.toml` |
| **Claude Code (CLI)** | run the `claude mcp add ouso-code …` line that setup prints |

## The rhythm

Four calls, and your agent stops forgetting — and stops wasting frontier-model tokens on tiny work:

```
memory_set_workspace   ← on open: bind repo, branch, open files (later calls auto-scope)
memory_route_task      ← before choosing a model: decide frontier vs lower-cost handoff
memory_recall_code     ← before a model call: pull the memories that matter for the task
memory_add_fact        ← after a decision or debug win: capture it in one line
```

That's it. Your agent recalls the right context going in, and banks what it learns coming out.

| Tool | What it does |
|:--|:--|
| `memory_set_workspace` | Bind repo, branch, open files so later calls auto-scope |
| `memory_route_task` | Recommend frontier/balanced/economy model use and generate a shared-memory handoff prompt |
| `memory_recall_code` | Hybrid recall of the memories that matter for a query |
| `memory_add_fact` | Capture a decision / insight / fix instantly |
| `memory_store` | Persist conversation turns; keeps the salient one |
| `memory_index_anchor` | Link a file/symbol to a memory (no whole-repo indexing) |
| `memory_list_recent` | List the most recent memories for this repo |
| `memory_record_delegate_result` | Store lower-cost model/subagent results back into the shared memory |

## Model routing

Most teams burn their best model on everything: orchestration, risky refactors, one-line tests, README
edits. Ouso Code adds a memory-backed router so Cursor, Codex, and Claude Code can use a simple split:

- **Frontier models** (`gpt-5.5`, `claude-opus-4.8`, or your configured names) plan, coordinate, and
  review risky work.
- **Balanced/economy models** (`gpt-5.3-code-spark`, `claude-sonnet`, or your configured names) handle
  small implementation, tests, docs, and narrow subagent tasks.
- **Ouso memory** is the shared context layer, so the cheaper model gets the same repo decisions and can
  write its result back for the orchestrator to review.

Call `memory_route_task` before picking a model:

```json
{
  "task": "Add a focused unit test for JWT refresh-token rotation.",
  "task_kind": "test",
  "risk": "low",
  "files": ["src/auth/tokens.ts"]
}
```

It returns `primary_tier`, `delegate_tier`, risk reasons, recalled memories, and a ready-to-paste
`handoff_prompt` for the lower-cost model/subagent. MCP cannot force an IDE's model picker to switch;
the tool gives the current model a concrete routing packet and shared-memory prompt. After the delegate
finishes, call `memory_record_delegate_result` so the orchestrator and every future model can recall the
work. See the full routing manual: [`docs/MODEL_ROUTING.md`](./docs/MODEL_ROUTING.md).

## How recall works

Repo-scoped memories are ranked by four independent, well-known signals and combined with a
**vector-dominant** weighted blend — semantic match leads; keyword, recency, and workspace overlap rescue
or break near-ties. When a query explicitly asks for the current/latest state, recency gets a
transparent boost so stale notes stop winning just because they are semantically similar.

| Signal | Method | Default |
|:--|:--|:--|
| Semantic | cosine over embeddings | your model's dimension |
| Lexical | Okapi BM25 (code-aware: splits `camelCase`/`snake_case`) | `k1=1.2, b=0.75` |
| Recency | exponential decay | 30-day half-life |
| Workspace | active-file overlap | on/off |
| Blend | min-max normalized, vector-dominant | base `vector 1.0 / lexical 0.35 / recency 0.15 / workspace 0.35`; freshness-intent recency `1.0` |

Every constant is a **documented public default** (override via `OUSO_RECALL_WEIGHTS`) — nothing is
secretly tuned. Recall only scores memories embedded with the **same model**; switch models?
`npm run reembed`.

## Reproducible evaluation

The repository includes synthetic fixtures that compare keyword-only, vector-only, and hybrid ranking
over the same memories. Run both evaluations with your chosen embedder:

```bash
npm run compare
npm run compare:current
```

The second command tests a deliberately difficult case: an old fact and a newer superseding fact are
both present, and the query asks what is true now. Results are printed from the model and configuration
you actually ran. The deterministic mock embedder is useful for CI behavior tests, but it is not a
quality benchmark; use Ollama or a real OpenAI-compatible embedding model for product evaluation.

Ouso Code exposes transparent local retrieval methods and their limitations. Fixed performance claims
are intentionally omitted until a versioned result bundle records the model, configuration, raw output,
and exact commit together.

## Upgrade to hosted Ouso Recall

Ouso's hosted product uses the same MCP tool boundary, so you can swap the server entry without changing
the surrounding editor workflow:

```bash
npx -y @ouso-ai/mcp-bridge   # needs OUSO_API_KEY from https://ouso.ai
```

## Configuration

<details>
<summary>Environment variables (all optional — local-first defaults work out of the box)</summary>

```env
DATABASE_URL=file:./data/ouso-code.sqlite     # your local store

OUSO_EMBED_PROVIDER=ollama                     # ollama | openai | azure | mock
OUSO_EMBED_MODEL=nomic-embed-text
OLLAMA_BASE_URL=http://localhost:11434

# Cloud (OUSO_EMBED_PROVIDER=openai) — OpenAI / Azure /v1 / any compatible proxy:
# OPENAI_API_KEY=sk-...           OR   AZURE_OPENAI_API_KEY=...
# OPENAI_BASE_URL=https://api.openai.com/v1   AZURE_OPENAI_ENDPOINT=https://<r>.openai.azure.com/openai/v1
# OPENAI_EMBED_MODEL=text-embedding-3-small   AZURE_OPENAI_EMBEDDING_DEPLOYMENT=...
# OUSO_EMBED_DIM=1024             # optional, force embedding dimension

# OUSO_RECALL_WEIGHTS=1.0,0.35,0.15,0.35   # vector,lexical,recency,activeFile; explicit override disables freshness boost
# OUSO_FUSION=weighted                # weighted (default) | rrf
# OUSO_STORAGE_DRIVER=sqlite          # only sqlite is built in today

# Optional display labels for memory_route_task handoff prompts:
# OUSO_MODEL_FRONTIER=gpt-5.5,claude-opus-4.8
# OUSO_MODEL_BALANCED=claude-sonnet,gpt-5.3-code-spark
# OUSO_MODEL_ECONOMY=gpt-5.3-code-spark,claude-sonnet
```

</details>

## FAQ

<details>
<summary><strong>Same memory in Cursor and Claude?</strong></summary>
Yes — point every IDE config at the same <code>DATABASE_URL</code>. <code>caller</code> records which IDE wrote each memory.
</details>
<details>
<summary><strong>Do you index my whole codebase?</strong></summary>
No. Memories are what you capture (facts, conversation turns) plus optional file/symbol anchors — not a repo-wide index.
</details>
<details>
<summary><strong>Is my data sent anywhere?</strong></summary>
Not with the default local setup (Ollama + SQLite). Only if you choose a cloud embedding provider does text go to that API.
</details>
<details>
<summary><strong>How are the benchmark numbers produced?</strong></summary>
By the committed scenarios in <code>examples/eval/</code>, scored on your machine via <code>npm run compare</code> and <code>npm run compare:current</code>. Nothing is hand-entered.
</details>
<details>
<summary><strong>Commercial use?</strong></summary>
Personal and internal company use is free. Hosted competing products or reconstructing Ouso Recall internals need permission — see <a href="./LICENSE.md">LICENSE.md</a> · admin@ouso.ai
</details>

## Development

```bash
npm test                                 # typecheck + leak scan + smoke + routing + shared memory + MCP + maintenance tests
npm run typecheck
npm run leak-scan                         # blocks proprietary identifiers from leaking in
OUSO_SMOKE_MOCK=1 npm run test:smoke
npm run test:routing                      # model-routing acceptance tests
npm run test:shared                       # cross-IDE/shared-memory behavior
npm run test:mcp                          # starts the real MCP server and calls every tool
npm run test:maintenance                  # migrate + reembed maintenance paths
npm run eval                              # recall@k on committed scenarios
npm run compare                           # method comparison (this README's numbers)
npm run compare:current                   # the current-state task
```

`npm test` is the release gate: it uses mock embeddings, starts the real MCP stdio server, calls every
public tool, verifies model routing and delegate-result recall, and checks migration/re-embedding paths
without needing Ollama or an API key.

---

<p align="center">
  <a href="https://ouso.ai"><strong>Ouso Recall</strong></a> · <a href="https://github.com/Ouso-ai/Ouso-Code">GitHub</a> · <a href="mailto:admin@ouso.ai">admin@ouso.ai</a><br />
  <sub>Free for personal &amp; internal use · <a href="./LICENSE.md">License</a></sub>
</p>