Scope

A wrong Scope rarely errors. Search is just empty.

Most PowerContext operations require a scope_id. That value decides which set of data the request reads or writes.

A wrong Scope often looks like missing data. You wrote something already, yet search stays empty. The more serious failure is using one Scope for projects or tenants that should remain separate.

Resolve Scope as an application decision, not a convenience fallback. In a multi-tenant service, authentication and authorization choose the allowed tenant and project first. Only then should the adapter receive the corresponding scope_id.

What Scope isolates

PowerContext keeps related state under the same scope_id. That set includes the Source journal and processing cursor, the Memory lifecycle and active search projections, the Experience and Skill Candidate Inbox, Handoff history and Work continuity, and scope-local runtime cache entries, locks, and statistics.

Another Scope cannot read this data unless the application writes it there separately.

What Scope does not do

Scope is not a security identity.

Knowing scope_id="project:payments" does not prove that the caller belongs to the payments team or may use a write tool. Bearer authentication, Server deployment boundaries, and host permission gates control access.

Scope also grants no execution authority. Recalled content from the correct Scope is still historical evidence. The agent must follow current system and user instructions and check the live workspace.

Do not accept a user-controlled string as an authorized Scope. Authenticate and authorize the caller first, then map the request to an allowed scope_id.

Choose a stable Scope

A useful Scope survives the work. It should not change with every session.

Scenario	Prefer	Avoid
One code repository	A normalized Git remote or explicit project ID	A temporary worktree path
Multi-tenant service	An explicit Scope mapped from an authenticated tenant or project	The service process working directory
Local project without Git	A stable path hash when the adapter supports it, or an explicit Scope	A new random ID on every run
Sharing across hosts	The same stable value on each host	Each host’s session ID

Scope strings are case-sensitive. project:PowerContext and project:powercontext select different data.

There is no universal derivation order

Integrations derive Scope from the information their host provides. Their rules differ.

Integration	Current derivation
Pydantic AI agent adapter	Constructor string or callback, then environment, a normalized Git remote, and a local path hash
LangGraph	Invocation Scope or environment, then a normalized network Git remote. It errors if that is missing
LangChain	Invocation Scope or environment, then a normalized network Git remote. It errors if that is missing
Codex / Claude Code	Workstream binding where applicable, Git remote, or project path. See each host page for exact precedence
OpenClaw	Trusted agent identity. Project mode adds a project hash but retains the agent dimension

The mental model gives selection rules rather than one fictional precedence list. Keep adapter-specific fallback behavior on the adapter page.

Git remotes are normalized

Integrations remove credentials from a remote URL before deriving Scope. These URLs should identify the same repository, and the token must not appear in the Scope.

https://user:[e-mail]/org/repo.git
https://example.com/org/repo.git

LangGraph and LangChain detect Windows drive-letter paths so they are not mistaken for SCP-style remotes. Other adapters do not all apply the same guard. On Windows or with unusual Git configuration, prefer an explicit Scope and inspect the derived value.

Share data across hosts

Codex and Claude Code can derive the same project Scope for one repository. Memory stored explicitly in one host can then be recalled in the other.

Sharing requires all three conditions. Both hosts connect to the same PowerContext Server. They resolve to exactly the same scope_id. Their reads and writes use the required access authorization.

Similar-looking directories are not enough. When sharing fails, inspect the final Scope before debugging search.

OpenClaw project mode currently keeps the agent ID in its Scope. Two agents in the same project do not automatically share a pure project Scope.

ScopeCache inside the Server

The Server caches runtime composition and one scope-local write lock for active Scopes. Its default capacity is 128 inactive entries.

This is not a data cache. Eviction does not delete Sources, Memory, or Handoffs from the database. An entry with active operations or lock waiters cannot be evicted. The cache may temporarily exceed capacity when every entry is active. After operations finish, the Server trims the least recently used inactive entries.

Writes in one Scope are serialized to protect head and cursor updates. Read-only search and an in-progress rerank should not all be serialized behind that write lock.

Common failures

A write succeeded, but the Dashboard is empty

Check that the Dashboard and client use exactly the same Scope. Changing the database URL also reveals a different data set and can look like a Scope problem. Walk through Verify Scope statistics in the Dashboard.

Two tenants see the same Memory

Make sure the application did not use the service process working directory or one fixed string for every tenant. Resolve Scope from an authorized tenant or project mapping.

LangGraph raises MissingScope in a local directory

LangGraph does not fall back to a local path hash when no network Git remote is available. Pass PowerContextScope(scope_id=...) for the invocation.

Every new session starts from scratch

The application probably used a session ID as Scope. Use a stable project or tenant Scope instead.

How you know the boundary holds

1. The Scope is stable and free of credentials.
2. A multi-tenant application authorizes first and selects Scope second.
3. Hosts that should share data resolve to exactly the same value.
4. Adapters do not all share the same fallback.
5. Cache eviction is not deletion of durable data.

If any of those fail, start with Troubleshooting. Continue with fail-open to decide which failures may leave the original task running and which operations must report an error.

Next

See which failures may continue

If automatic recall fails, keep working. If you explicitly ask to write, the failure must stay visible.

Read fail-open

Match the closest failure

Search is empty, the page is blank, or doctor passed and it still fails? Start with a case this site already covers.

Open troubleshooting