[Feature]: Multi-bundle search across user-level and project-level `knowledge/`

[kurodaritsu]

Is your feature request related to a problem or limitation?

I'm running Claude Code with a user-level ~/.claude/ and a per-project .claude/ setup. I'd like okf-agent-memory to implement that same idea, meaning there's a user-level ~/knowledge/ bundle for things true across every repo (e.g. web/programming research files) and a project-level ./knowledge/ for things that are true only in one repo.

The MCP server currently can only use a single bundle per call via bundle arg. Though, there is OKF_MCP_ROOT that I can use as a hack, it's only a single root, so one server instance can't reach both ~/knowledge and <project>/knowledge at the same time unless I set the it to something like $HOME, which looks ugly to me given create_concept and update_concept write through the same path check.

Though, this idea looks far fetched to me because this means dealing with ID collisions, handling graph builds and validations between user and project level, multi-root config shenanigans, etc.

Proposed Solution / Enhancement

Ideal: okf search to have an optional scope arg (user / project / default: both).

One server instance load an ordered list of bundles, each with a scope label, and search their union. Probably something like this in the config:

OKF_MCP_BUNDLES="user=/home/me/knowledge:project=./knowledge"

Not sure if this is the best approach but I'm open to alternatives.

Alternatives Considered

Current workaround is registering two MCP server instances, one for user scope and another at project scope, so the tools are named like mcp__okf-user__search and mcp__okf-project__search.

Although, this workaround have some limitations:

1. Separate ranked list - Two bundles that are indexed separately produce separate scores, and merging the list result by score here probably doesn't work. idf is derived from the per-bundle concept count:
   

   okf-agent-memory/pkg/okf/search.go

   Line 47 in b388dd7

   N := float64(len(b.Concepts))

   
   

   okf-agent-memory/pkg/okf/search.go

   Line 96 in b388dd7

   idf := math.Log(1.0 + (N-docFreq+0.5)/(docFreq+0.5))

2. The agent has to remember to call both servers - Even if I tell the agent to query from both servers (in CLAUDE.md), it'll eventually forgets one server or the other and I have to keep reminding it via hook.

Additional Context

Claude Code

[sknr]

Thanks for opening this issue, @kurodaritsu! This is a fantastic and very timely proposal.

Your analysis of the current pain points is spot-on:

1. LLM Cognitive Fatigue: Asking an agent to query multiple separate MCP servers (okf-user vs okf-project) causes it to routinely drop or forget one of them across long multi-turn sessions.
2. IDF Skewing: Merging two independently ranked BM25/IDF score lists produces mathematically distorted rankings because $N$ (corpus size) and document frequencies differ per scope.
3. Confinement Dilemma: Setting OKF_MCP_ROOT=$HOME breaks path confinement (CWE-22) and allows write operations to escape into the entire user directory.

As you noted, all okf CLI commands and MCP tools already support the bundle argument to target arbitrary directory paths within a single server root (e.g., monorepos with packages/core/knowledge and packages/web/knowledge). But cross-boundary (User vs. Project) memory requires a structured architectural model.

Before implementing a multi-scope union search, we need to address two critical design challenges:

---

1. The Precedence & Stack Hierarchy (Preventing Scope Sprawl)

If we allow mounting arbitrary scopes, we quickly face the risk of uncoordinated sprawl (scope: user, scope: project, scope: team-docs, scope: special).

Instead of treating scopes as a flat list, we should adopt a Layered Stack Model (similar to git config, CSS, or Nix overlays), where each mounted scope has:

• A Priority/Rank: (e.g., scope: project with priority 100 > scope: user with priority 50 > scope: system with priority 10)
• A Permission Mode: By default, only scope: project is read-write. Global (scope: user) and vendor (scope: system) scopes should be mounted as read-only in project sessions. This prevents an agent working in a client repository from accidentally mutating your personal ~/.config/okf/knowledge.

2. Conflicting & Contradictory Knowledge ("Local Beats Global")

What happens when two scopes provide opposite guidance? (e.g., scope: user says "always use TDD", while scope: project says "never use TDD"):

• A. Exact ID Collision (Shadowing): If both scopes contain the same concept ID (e.g., convention/testing), the higher-priority layer (scope: project) completely shadows the lower layer (scope: user). The shadowed concept is omitted or flagged as shadowed.
• B. Semantic Conflict (Different IDs): BM25 has no notion of semantic negation; it will return both concepts. To prevent agent confusion:
  1. Search results must return Scope & Priority Metadata (e.g., scope: "project", priority: 100).
  2. The canonical agent workflow rules (AGENTS.md) define the golden rule: Local beats Global — project-level knowledge strictly supersedes user-level preferences whenever they conflict.

3. Graph Hermeticity & Validation

A project bundle tracked in Git must remain 100% self-contained. If a concept in scope: project links via okf relate to a personal concept in scope: user, okf validate --strict will fail in CI or for any teammate cloning the repo. Therefore, cross-scope relationships must either be prohibited or treated as non-validating external hyper-references.

---

Proposed Implementation Direction

1. Multi-Scope MCP Configuration:
   Allow configuring an ordered list of allowed scopes in the MCP server config (or via env var like OKF_MCP_SCOPES="project=./knowledge:user=~/.config/okf/knowledge").
   • This keeps path confinement safe: requests can only access explicitly whitelisted scope directories.
2. Composite In-Memory Searcher:
   • okf_search queries across all mounted scopes in a single turn using a unified BM25 index ($N = N_{\text{project}} + N_{\text{user}}$).
   • Search results include the scope label and its priority weight.
   • Optional parameter scope ("project", "user", or "all", defaulting to "all" for search).
3. Scoped Show & Safe Writes:
   • okf_show defaults to scope: project, or falls back down the stack (or accepts an explicit scope: "user").
   • okf_create, okf_update, and okf_relate strictly default to scope: project unless explicitly directed to a writable scope.

How does this layered/stack approach align with your workflow in Claude Code? Would love to get your thoughts on this!