Install and run the Server

Start the minimum Server first. Do not add a model on the first run.

Start the minimum Server first. It has no generation or embedding model, but it can already store a Memory you write, run full-text search, and expose the same data through HTTP, the Python Client, and MCP.

Do not add a model on the first run. If something gets stuck, you only need to check install, the data directory, Scope, and the connection. Finish this loop, then add inference. Otherwise a provider failure can look like a broken database or a broken integration.

Install flags, API contracts, and deploy settings follow the latest published official docs. This page only helps you start the local Server and see what it can do now.

The documented install path is macOS or Linux, Python 3.11 or later. This tutorial does not provide an unverified Windows workaround.

Prerequisites

The documented environment is:

• macOS or Linux;
• Python 3.11 or later;
• Git;
• uv.

PowerContext supports Python <4.0.

Install the CLI and Server

Install the current master:

uv tool install --force \
  "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"

uv tool uses an isolated environment and leaves no repository checkout in the current directory. --force also matters for updates: when the same Git requirement is already installed, it fetches and replaces the selected ref instead of returning already installed.

For local learning, follow the ref on the page you are reading. This page and the common / coding-agent setup pages use @master so the tutorial can track current docs.

For a reproducible deploy, do not follow master. Pin one reviewed commit, then use that same ref for the CLI, Server, and host plugin. Write the full commit hash when you pin. Do not mix a short hash and a long hash in the same command set.

A powercontext[client] extra installed inside the uv tool environment is not importable from an unrelated Python project. Install the client extra in the project that runs Client code.

Start the local Server

powercontext server run

The default configuration is:

Item	Default behavior
Address	http://127.0.0.1:8000
Dashboard	/
Streamable HTTP MCP	/mcp; see Connect with MCP
Database	Persistent SQLite in the user data directory
Bearer auth	Disabled for the default loopback setup
Generation / embedding	Not configured
Search	auto, fts

On macOS, the database is usually stored at:

~/Library/Application Support/powercontext/powercontext.db

On Linux, it is usually:

~/.local/share/powercontext/powercontext.db

When POWERCONTEXT_HOME is set, the default database moves under that directory. A new data directory or database URL opens another database. That looks like a lost Scope.

Ctrl-C shuts the Server down cleanly. Starting it again reopens the same database.

Inspect runtime status

Open another terminal:

powercontext doctor
powercontext ready
powercontext capabilities

These three commands answer different questions.

doctor

Checks the installed package, Server liveness, and Server readiness. It exits with zero only when every check is ok.

When liveness fails, readiness is marked skipped. degraded also produces a non-zero doctor result because at least one configured inference check failed; it does not necessarily mean the database is unavailable.

ready

Distinguishes:

• ready: every configured check passes;
• degraded: an optional inference check failed, with HTTP 200;
• not_ready: the Runtime or database is unavailable and the readiness endpoint returns HTTP 503. The current CLI prints that 503 as a Server error instead of rendering the full not_ready response; use doctor or inspect /health/ready directly for dependency details.

capabilities

A minimum Server should report something like:

Source types: content
Artifact families: memory, experience, skill, handoff
Memory extraction: disabled
Experience generation: disabled
Managed Skill generation: disabled
External Skill Registry: disabled
Handoff generation: disabled
Search modes: auto, fts
Context versions: powercontext.prepared-context.v1

The presence of an Artifact family does not mean model-backed generation for that family is enabled. Check the corresponding capability boolean.

Open the Dashboard at:

http://127.0.0.1:8000/

With no Dashboard Scope configured, the page is empty. A Dashboard initialization failure only logs a warning. HTTP and MCP still work. To check counts for the same Scope, follow Verify Scope statistics in the Dashboard and use the same scope_id.

Check what works without a model first

The minimum Server still supports:

• Source capture;
• explicit Memory remember, search, revise, and retire;
• FTS;
• typed Experience and Skill proposals with Candidate Review;
• Prepared Handoff finalize, commit, and continue;
• PreparedContext construction when the Scope has recallable content.

It does not support:

• model extraction from Source to Memory;
• model generation for Experience, Skill, or Handoff;
• vector or hybrid search;
• model-backed reranking.

So the first loop starts with a Memory you already accept: write it, find it with search_memory, and use prepare_context to get a cited PreparedContext. Confirm the data is still there, the Scope matches, and the Citation is present before you add a provider. Extracting Memory from a Source, and generating a Handoff with a model, wait for later pages.

Install the Client in a Python project

In the project that runs the examples:

uv add \
  "powercontext[client] @ git+https://github.com/oceanbase/powercontext.git@master"

Confirm that the project uses Python 3.11 or later:

uv run python --version

The next page imports the public API through:

from powercontext.client import PowerContextClient
from powercontext.http import RememberMemoryRequest

Do not import internal generated modules from powercontext.http._generated.

.env is not loaded automatically

The PowerContext CLI does not search the current directory for .env. Pass the file explicitly:

powercontext server run --env-file .env

A full-capability configuration starts with:

powercontext config init --output .env
powercontext config show --env-file .env
powercontext config validate --env-file .env
powercontext server run --env-file .env

Generation and scheduling are separate settings. A generation model turns extraction on. It does not start the periodic scheduler. You can still call flush_memory yourself.

Embedding needs the model, profile ID, and dimension as one set. If any piece is missing, validation should fail. Do not start a vague half-vector mode.

Authentication and remote access

The default Server listens on loopback, so disabled authentication is reasonable for local development.

A non-loopback bind requires authentication or an explicit unsafe opt-in by default. The Python Client also rejects plaintext HTTP to a non-loopback host. Remote and production deployments should use TLS and a bearer token. Never put the token in the URL.

When authentication is enabled, the Client reads a bare token:

export POWERCONTEXT_CLIENT_API_TOKEN="replace-with-token"

It constructs:

Authorization: Bearer replace-with-token

Common startup stuck points

doctor cannot reach the Server

Confirm that powercontext server run is still running and that port 8000 is free. For a custom address, put the option that belongs to doctor after the subcommand:

powercontext doctor \
  --server-url http://127.0.0.1:9000

The root --server-url applies to Client content commands and does not replace the separate doctor address.

You created .env, but capabilities did not change

Did the Server command include --env-file .env? The CLI does not load it on its own.

capabilities lists only auto, fts

The Server is working in full-text-only mode. That is expected until vector or hybrid search is fully configured.

ready is degraded

Inspect the failed dependency check. Database operations that do not need that inference capability may still work. Operations that need the failed provider will not.

Data disappeared after restart

Check POWERCONTEXT_HOME, the database kind, and the database URL, then check scope_id. Each one changes which data you see. If it still does not match, start with Troubleshooting.

How you know it worked

Before you continue, confirm:

• powercontext doctor passes on the minimum setup.
• powercontext capabilities lists auto, fts.
• The Dashboard opens, or you turned it off on purpose.
• The example Python project can import PowerContextClient.
• The stable Scope for this tutorial is project:powercontext-101.
• The next step is: write a Memory, find it with search_memory, then get a cited PreparedContext from prepare_context.

Next step

Common API tour

Use the Python Client to write one Memory, find it, and get a cited PreparedContext.

Run the first loop

If you are stuck

Can’t find what you wrote, see an empty page, or a check passed and it still fails? Start there.

Open troubleshooting