@orquentra/codebuddy 2.5.0 → 2.6.2

package/CLAUDE_CODEX.md

@@ -266,8 +266,8 @@ Create `.mcp.json`:
       "args": ["serve"],
       "env": {
         "DATABASE_URL": "postgres://codebuddy:codebuddy@localhost:5432/codebuddy",
-        "HF_TOKEN": "hf_your_token",
-        "CODEBUDDY_NAMESPACE": "your-project"
+        "CODEBUDDY_NAMESPACE": "your-project",
+        "CODEBUDDY_PROJECT_ROOT": "/absolute/path/to/your-project"
       }
     }
   }
@@ -338,7 +338,7 @@ args = ["serve"]
 [mcp_servers."codebuddy-your-project".env]
 CODEBUDDY_NAMESPACE = "your-project"
 DATABASE_URL = "postgres://codebuddy:codebuddy@localhost:5432/codebuddy"
-HF_TOKEN = "hf_your_token"
+CODEBUDDY_PROJECT_ROOT = "/absolute/path/to/your-project"
 ```
 
 Restart Codex after installing or changing an MCP entry.
@@ -413,7 +413,9 @@ codebuddy migrate
 If Claude Code does not show CodeBuddy tools:
 
 - confirm `.mcp.json` is in the project root
-- confirm `HF_TOKEN`, `DATABASE_URL`, and `CODEBUDDY_NAMESPACE`
+- confirm `DATABASE_URL`, `CODEBUDDY_NAMESPACE`, and that the server starts in (or
+  `CODEBUDDY_PROJECT_ROOT` points to) a folder with `.codebuddy/config.json`.
+  `HF_TOKEN` is needed only for `provider.type: "huggingface"`.
 - restart Claude Code
 
 If Codex does not show CodeBuddy tools:

package/README.md

@@ -20,6 +20,14 @@ The setup wizard configures the project and agent integration. Project context
 works without a database; semantic memory recall optionally uses PostgreSQL
 with pgvector and a local Hugging Face embedding model (no token needed).
 
+Run setup inside the project you want CodeBuddy to read. Claude Desktop
+registration saves that folder's absolute path, so restarting the desktop app
+does not change which project is indexed. `serve` requires an initialized
+project (`.codebuddy/config.json`) and refuses filesystem roots and home folders.
+Older desktop registrations without a project path can be repaired by running
+`codebuddy claude install` from the initialized project folder, then restarting
+Claude Desktop.
+
 ## What it does
 
 - **Task context:** relevant files, symbols, code excerpts, nearby dependencies,

package/WORKFLOW.md

@@ -12,7 +12,7 @@ CodeBuddy is a shared notebook for AI agents.
 - Embeddings are prepared in the background so related memories can be found later.
 - When an agent asks a question, CodeBuddy picks the most useful memories that fit inside the token budget.
 - Agents can share facts with other agents through namespaces.
-- The CLI helps you see whether the database, Hugging Face models, and memory index are healthy.
+- The CLI helps you see whether the database, the embedding model (local by default), and memory index are healthy (`codebuddy doctor`, `codebuddy models`).
 
 ## Graphical Flow
 
@@ -38,7 +38,7 @@ CodeBuddy Core
      |
      +--> In-process embedding worker
      |      |
-     |      +--> Hugging Face resilience layer
+     |      +--> embedding provider (local model by default; Hugging Face or OpenRouter optional)
      |      |      |
      |      |      +--> retry/backoff
      |      |      +--> cold-start wait
@@ -71,7 +71,7 @@ Planner packs best items under token budget
 5. In one transaction, it writes the memory row and creates an embedding row with `status=pending`.
 6. For facts and summaries, it also writes a Markdown file.
 7. If the same content or idempotency key already exists, it returns the original ID with `deduplicated: true`.
-8. After the transaction, the in-process worker asks Hugging Face for embeddings.
+8. After the transaction, the in-process worker asks the embedding provider (the local model by default) for embeddings.
 9. The embedding row becomes `ready` or `failed`.
 
 ## Migration And Recovery Flow
@@ -130,7 +130,7 @@ source delete          ---> B remains
 - database connection
 - `pgvector` extension
 - vector index health
-- Hugging Face model reachability
+- embedding model readiness (`codebuddy models`)
 - gated model errors
 - cold vs warm model state
 - rate-limit pressure
@@ -140,7 +140,7 @@ source delete          ---> B remains
 
 ## Why Async Embeddings Matter
 
-Hugging Face free-tier models can be cold or rate-limited. CodeBuddy should not block a memory write just because a model needs time to wake up. It stores the memory first, marks the embedding as pending, and lets recall use recency until vectors are ready.
+A hosted embedding API can be cold or rate-limited, and the local model downloads once on first use. CodeBuddy should not block a memory write just because a model needs time to wake up. It stores the memory first, marks the embedding as pending, and lets recall use recency until vectors are ready.
 
 ## What The User Sees