Ouso Code

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

Related MCP server: AIVectorMemory

Install

Works on Windows, macOS, and Linux. No API key needed with local Ollama:

ollama pull nomic-embed-text   # default local embedder

Windows PowerShell:

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

macOS / Linux:

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

Manual path for any OS:

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.

Connect your IDE

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.

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:

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

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.

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:

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:

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

Configuration

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

FAQ

Development

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.