curu-memory 0.2.0__tar.gz → 0.3.0__tar.gz

{curu_memory-0.2.0 → curu_memory-0.3.0}/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project are in this file. The format follows [Keep a
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-11-01
+
+### Added
+
+- The public Python API in `curu_memory.__all__`: `build_space`, `open_knowledge` and `Knowledge`, with its result types and errors. `Knowledge.search`, `get_concept` and `neighbours` give the results of the matching tools.
+- The library reads as one principal: a person, the agent of one grant, or nobody. It uses the rules of the server, and each refused read writes the same audit line.
+- `tests/contract/public_api.txt`: a test fails when `__all__` changes and the snapshot does not.
+
+### Changed
+
+- **Breaking:** `mcp`, `starlette` and `uvicorn` moved to the `server` extra. `serve` and `browse` need `curu-memory[server]`. Without it, they stop with exit code 78 and name the extra. `index`, `search` and `access` need no extra.
+- `tool_result_from` moved from `curu_memory.errors` to `curu_memory.server`, so the errors import no MCP package.
+
 ## [0.2.0] - 2026-11-01
 
 This is the first release on PyPI. Version 0.1.0 was not published.

curu_memory-0.2.0/README.md → curu_memory-0.3.0/PKG-INFO

@@ -1,3 +1,23 @@
+Metadata-Version: 2.5
+Name: curu-memory
+Version: 0.3.0
+Summary: A shared knowledge base and GraphRAG store for ComfyUI and generative media, served to agents over MCP.
+Project-URL: Repository, https://github.com/darth-veitcher/curu-memory
+Project-URL: Documentation, https://github.com/darth-veitcher/curu-memory#readme
+Project-URL: Changelog, https://github.com/darth-veitcher/curu-memory/blob/main/CHANGELOG.md
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: httpx2>=2.10
+Requires-Dist: markdown-it-py>=4.0
+Requires-Dist: pydantic>=2.12
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: server
+Requires-Dist: mcp==2.3.0; extra == 'server'
+Requires-Dist: starlette>=1.0; extra == 'server'
+Requires-Dist: uvicorn>=0.31.1; extra == 'server'
+Description-Content-Type: text/markdown
+
 # curu-memory
 
 ## What is this
@@ -23,24 +43,25 @@ curu-memory is a shared knowledge base for ComfyUI and generative media. It read
 | Browse the knowledge in a web browser | `curu-memory browse` | [Browse the knowledge](#browse-the-knowledge) |
 | Read a concept and its links | The `get_concept` and `concept_neighbours` tools | [Read a concept and follow its links](#read-a-concept-and-follow-its-links) |
 | Find why a call failed | The `code` of the error | [Handle errors](#handle-errors) |
+| Build and read the knowledge from a Python program | `curu_memory.open_knowledge()` | [Use curu-memory from Python](#use-curu-memory-from-python) |
 
 ## Install
 
 You need Python 3.12 or later and [uv](https://docs.astral.sh/uv/).
 
 ```bash
-uv tool install git+https://github.com/darth-veitcher/curu-memory
+uv tool install "curu-memory[server] @ git+https://github.com/darth-veitcher/curu-memory"
 ```
 
-This installs the `curu-memory` command.
+This installs the `curu-memory` command with the `server` [extra](#glossary). `serve` and `browse` need the extra. Without it, `index`, `search` and `access` work, and `serve` and `browse` stop with exit code 78.
 
 To install a release from PyPI, give a version range:
 
 ```bash
-uv tool install "curu-memory>=0.2,<0.3"
+uv tool install "curu-memory[server]>=0.3,<0.4"
 ```
 
-A program that uses curu-memory as a library pins the same range in its `pyproject.toml`. A new minor version can change the Python API or the MCP tools, so the range stops before the next minor version.
+A program that uses curu-memory as a library pins a range in its `pyproject.toml`, with no extra. A new minor version can change the Python API or the MCP tools, so the range stops before the next minor version.
 
 ## Quickstart
 
@@ -568,11 +589,58 @@ The `curu-memory` command uses these exit codes:
 | 0 | Success. |
 | 1 | `index` skipped a file, the embedder failed, another index run held the lock, or the embedder model was not the model of another space. `search` found no index, or no readable space. `access` refused a change. |
 | 2 | A usage error, for example `--limit 51`. |
-| 78 | A configuration error, for example HTTP with no token. |
+| 78 | A configuration error, for example HTTP with no token, or `serve` with no `server` extra. |
+
+## Use curu-memory from Python
+
+Use the library to build a space and to read it from a Python program, with no server. Import each name from `curu_memory` only. The names of `curu_memory.__all__` are the public API. Each other name can change in any release. The public API starts with version 0.3.0, so a program pins `curu-memory>=0.3,<0.4`.
+
+```python
+from pathlib import Path
+
+import curu_memory
+
+report = curu_memory.build_space(Path("knowledge"))
+print(report.concepts_indexed, len(report.skipped))
+
+knowledge = curu_memory.open_knowledge()
+for hit in knowledge.search("VAE for WAN2.2 5B", limit=3).results:
+    print(hit.id, hit.space)
+
+concept = knowledge.get_concept("wan22-5b-vae")
+links = knowledge.neighbours(concept.id)
+```
+
+- `build_space` builds one space, as the index command does. `space=` names the space, and the default is `global`. A skipped file is not an error. The fields of the report are the values of [Index your knowledge](#index-your-knowledge), except `index`, for example `concepts_indexed`. `skipped` holds a (path, reason) pair for each skipped file.
+- `open_knowledge` reads as one [principal](#glossary). Give `person="<handle>"` to read the spaces of that person. Give `grant=<id>` to read only the space of that grant. With neither, the library reads `global` only.
+- An unknown, ended or revoked grant does not stop `open_knowledge`. Each read then raises `NoReadableSpace`. `serve --grant` stops at the start for such a grant.
+- Each read gets the readable spaces again. A removed role or a revoked grant stops the next read.
+- `search`, `get_concept` and `neighbours` give the same results as the tools `search_knowledge`, `get_concept` and `concept_neighbours`. Each hit gives its `space`.
+- Each refused read writes the line in the audit log that the server writes, with the name of the matching tool as the action.
+- `data_dir=` replaces the data directory. `env=` gives the `CURU_MEMORY_*` variables as a dictionary, for example the embedder settings of [Search by meaning](#search-by-meaning). With no `env`, the library reads the environment of the process.
+- The library does not use `CURU_MEMORY_PRINCIPAL` to select the principal. A value that is not a valid handle raises `ConfigError`.
+- The principal is not a security boundary in one process. The boundary is who can read the data directory.
+
+Each error is in `curu_memory`:
+
+| Call | Cause | Error |
+|---|---|---|
+| `build_space` | The concept directory does not exist, or the space name is not valid. `details.field` names the argument. | `InvalidArgument` |
+| `build_space` | Another index run holds the lock. | `IndexLocked` |
+| `build_space` | The embedder model is not the model of another space. | `IndexRefused` |
+| `build_space` | The embedder failed. The old index stays. | `EmbedderFailed` |
+| `build_space`, `open_knowledge` | A `CURU_MEMORY_*` variable is not valid. | `ConfigError` |
+| `open_knowledge` | No person has the handle, or `person` and `grant` are both given. | `InvalidArgument` |
+| each read | The principal can read no space. | `NoReadableSpace` |
+| `get_concept`, `neighbours` | No readable space holds the concept. | `ConceptNotFound` |
+| `search` | The question is empty or too long, or the limit is not from 1 to 50. | `InvalidArgument` |
+| each read | No readable space has an index. | `IndexMissing` |
+
+Each error except `IndexLocked` and `ConfigError` is a `CuruMemoryError`. Its `code` is the code that a tool gives, for example `concept_not_found`.
 
 ## Limits
 
-- On stdio, in the browser and with the static token, one process reads as one person (`CURU_MEMORY_PRINCIPAL`). On stdio, `serve --grant` makes the process read as the agent of one grant. Only the OIDC mode of HTTP gives each request its own person or agent.
+- On stdio, in the browser and with the static token, one process reads as one person (`CURU_MEMORY_PRINCIPAL`). In Python, each `Knowledge` reads as the principal of its `open_knowledge`. On stdio, `serve --grant` makes the process read as the agent of one grant. Only the OIDC mode of HTTP gives each request its own person or agent.
 - There is no encryption at rest yet.
 - The browser has no OIDC login.
 - Agents and persons cannot write knowledge through curu-memory yet. Edit the concept files, then run the index command.
@@ -590,7 +658,7 @@ The `curu-memory` command uses these exit codes:
 - A match between a question in words and a clip needs 0.68 or more with EmbeddingGemma 2. The limit comes from speech clips. Speech test clips scored from 0.73 with their own questions. Wrong clips and unrelated questions reached 0.64. Music and sound effects can score lower.
 - The index holds a copy of each media file. One hundred files of 2 MB make the index about 200 MB larger.
 - There is no file watcher. Run the index command after each change.
-- curu-memory has no public Python API yet. Each module is internal.
+- The Python API cannot search with media, and it cannot write a concept. Use `curu-memory search --media` or the tool `search_knowledge_by_media` for media.
 
 ## Technical notes
 
@@ -609,7 +677,8 @@ The `curu-memory` command uses these exit codes:
 - The concept rules are the same as the rules of the curu index, so each curu concept file indexes here.
 - The tool contracts are in [specs/001-okf-index-mcp-search/contracts/](specs/001-okf-index-mcp-search/contracts/).
 - curu-memory uses the official MCP Python SDK. It never loads model weights.
-- curu uses curu-memory as a library, and the version range of a release follows a version policy. See [ADR-019](project-management/ADRs/ADR-019-curu-uses-curu-memory-as-a-library.md).
+- curu uses curu-memory as a library, and the version range of a release follows a version policy. See [ADR-019](project-management/ADRs/ADR-019-curu-uses-curu-memory-as-a-library.md). `tests/contract/public_api.txt` holds the names of `curu_memory.__all__`. The contract is [specs/015-the-public-library-api/contracts/public-api.md](specs/015-the-public-library-api/contracts/public-api.md).
+- The core install has `pydantic`, `httpx2`, `markdown-it-py` and `pyyaml`. The `server` extra adds `mcp`, `starlette` and `uvicorn`.
 
 ## Develop
 
@@ -620,7 +689,7 @@ uv sync
 uv run pytest
 ```
 
-The default tests need no network, no GPU and no model. They use a fake embedder and a copy of the curu concept files. The tests with a real embedder have the `integration` marker. With no GPU embedder server, start the [development embedder](#glossary) first, as [tools/embedder_server/README.md](tools/embedder_server/README.md) says. Then run:
+`uv sync` installs the `server` extra, because the development group names it. The default tests need no network, no GPU and no model. They use a fake embedder and a copy of the curu concept files. The tests with a real embedder have the `integration` marker. With no GPU embedder server, start the [development embedder](#glossary) first, as [tools/embedder_server/README.md](tools/embedder_server/README.md) says. Then run:
 
 ```bash
 CURU_MEMORY_EMBEDDER_URL=http://127.0.0.1:30000 CURU_MEMORY_EMBEDDER_TIMEOUT=300 uv run pytest -m integration
@@ -654,6 +723,7 @@ The CI runs the same gates on each pull request and on each push to `main`. A re
 - **Data URI**: a text that holds the bytes of a file in base64, with their MIME type, for example `data:image/png;base64,...`.
 - **Data directory**: the directory of the index, the embedding cache, the access store `access.sqlite` and the audit log `audit.jsonl`. The default is `~/.local/share/curu-memory`, or `$XDG_DATA_HOME/curu-memory`. `CURU_MEMORY_DATA_DIR` changes it.
 - **Development embedder**: the CPU server in `tools/embedder_server/` that serves EmbeddingGemma 2 for the integration tier.
+- **Extra**: a named set of optional packages of a Python package, for example `server` in `curu-memory[server]`.
 - **Embedder**: a server that changes a text, an image, a clip or a video into an embedding.
 - **Embedding**: a list of numbers that holds the meaning of a text, an image, a clip or a video. Items with a near meaning have near embeddings.
 - **GraphRAG**: retrieval that uses a search and the links between concepts to give an agent its context.
@@ -671,11 +741,11 @@ The CI runs the same gates on each pull request and on each push to `main`. A re
 - **Web browser**: the program that shows web pages, for example Firefox.
 - **SHA-256**: a hash of 64 hexadecimal characters that the bytes of a file give. Different bytes give a different SHA-256.
 - **Unit**: one part of a concept that has its own embedding: the summary, the overview, a `##` section, an image, a clip or a video.
-- **Version range**: the lowest version and the first version to exclude, for example `>=0.1,<0.2`.
+- **Version range**: the lowest version and the first version to exclude, for example `>=0.3,<0.4`.
 - **Space**: a part of the knowledge with its own index: `global`, `team/<slug>` or `personal/<handle>`. Each request reads only the spaces that its caller can read.
 - **Team slug**: the short name of a team in a space name, for example `look` in `team/look`.
 - **Instance owner**: a person with `admin` on `global` and on each team space. The first registered person is an instance owner.
-- **Principal**: the person or the agent of a request: from `CURU_MEMORY_PRINCIPAL`, from `serve --grant`, from the OIDC token on HTTP, or `anonymous` with no principal.
+- **Principal**: the person or the agent of a request, or `anonymous` with no principal. It comes from `CURU_MEMORY_PRINCIPAL`, `serve --grant`, the OIDC token on HTTP or `open_knowledge`.
 - **Operator**: the person who runs `curu-memory access` and `curu-memory index` on the computer of the server.
 - **Access store**: `access.sqlite`, with the persons, the teams, the members, the agents and the grants.
 - **Audit log**: `audit.jsonl`, with one line for each change of access, each refused read and each refused token.

curu_memory-0.2.0/PKG-INFO → curu_memory-0.3.0/README.md

@@ -1,22 +1,3 @@
-Metadata-Version: 2.5
-Name: curu-memory
-Version: 0.2.0
-Summary: A shared knowledge base and GraphRAG store for ComfyUI and generative media, served to agents over MCP.
-Project-URL: Repository, https://github.com/darth-veitcher/curu-memory
-Project-URL: Documentation, https://github.com/darth-veitcher/curu-memory#readme
-Project-URL: Changelog, https://github.com/darth-veitcher/curu-memory/blob/main/CHANGELOG.md
-License-Expression: MIT
-License-File: LICENSE
-Requires-Python: >=3.12
-Requires-Dist: httpx2>=2.10
-Requires-Dist: markdown-it-py>=4.0
-Requires-Dist: mcp==2.3.0
-Requires-Dist: pydantic>=2.12
-Requires-Dist: pyyaml>=6.0
-Requires-Dist: starlette>=1.0
-Requires-Dist: uvicorn>=0.31.1
-Description-Content-Type: text/markdown
-
 # curu-memory
 
 ## What is this
@@ -42,24 +23,25 @@ curu-memory is a shared knowledge base for ComfyUI and generative media. It read
 | Browse the knowledge in a web browser | `curu-memory browse` | [Browse the knowledge](#browse-the-knowledge) |
 | Read a concept and its links | The `get_concept` and `concept_neighbours` tools | [Read a concept and follow its links](#read-a-concept-and-follow-its-links) |
 | Find why a call failed | The `code` of the error | [Handle errors](#handle-errors) |
+| Build and read the knowledge from a Python program | `curu_memory.open_knowledge()` | [Use curu-memory from Python](#use-curu-memory-from-python) |
 
 ## Install
 
 You need Python 3.12 or later and [uv](https://docs.astral.sh/uv/).
 
 ```bash
-uv tool install git+https://github.com/darth-veitcher/curu-memory
+uv tool install "curu-memory[server] @ git+https://github.com/darth-veitcher/curu-memory"
 ```
 
-This installs the `curu-memory` command.
+This installs the `curu-memory` command with the `server` [extra](#glossary). `serve` and `browse` need the extra. Without it, `index`, `search` and `access` work, and `serve` and `browse` stop with exit code 78.
 
 To install a release from PyPI, give a version range:
 
 ```bash
-uv tool install "curu-memory>=0.2,<0.3"
+uv tool install "curu-memory[server]>=0.3,<0.4"
 ```
 
-A program that uses curu-memory as a library pins the same range in its `pyproject.toml`. A new minor version can change the Python API or the MCP tools, so the range stops before the next minor version.
+A program that uses curu-memory as a library pins a range in its `pyproject.toml`, with no extra. A new minor version can change the Python API or the MCP tools, so the range stops before the next minor version.
 
 ## Quickstart
 
@@ -587,11 +569,58 @@ The `curu-memory` command uses these exit codes:
 | 0 | Success. |
 | 1 | `index` skipped a file, the embedder failed, another index run held the lock, or the embedder model was not the model of another space. `search` found no index, or no readable space. `access` refused a change. |
 | 2 | A usage error, for example `--limit 51`. |
-| 78 | A configuration error, for example HTTP with no token. |
+| 78 | A configuration error, for example HTTP with no token, or `serve` with no `server` extra. |
+
+## Use curu-memory from Python
+
+Use the library to build a space and to read it from a Python program, with no server. Import each name from `curu_memory` only. The names of `curu_memory.__all__` are the public API. Each other name can change in any release. The public API starts with version 0.3.0, so a program pins `curu-memory>=0.3,<0.4`.
+
+```python
+from pathlib import Path
+
+import curu_memory
+
+report = curu_memory.build_space(Path("knowledge"))
+print(report.concepts_indexed, len(report.skipped))
+
+knowledge = curu_memory.open_knowledge()
+for hit in knowledge.search("VAE for WAN2.2 5B", limit=3).results:
+    print(hit.id, hit.space)
+
+concept = knowledge.get_concept("wan22-5b-vae")
+links = knowledge.neighbours(concept.id)
+```
+
+- `build_space` builds one space, as the index command does. `space=` names the space, and the default is `global`. A skipped file is not an error. The fields of the report are the values of [Index your knowledge](#index-your-knowledge), except `index`, for example `concepts_indexed`. `skipped` holds a (path, reason) pair for each skipped file.
+- `open_knowledge` reads as one [principal](#glossary). Give `person="<handle>"` to read the spaces of that person. Give `grant=<id>` to read only the space of that grant. With neither, the library reads `global` only.
+- An unknown, ended or revoked grant does not stop `open_knowledge`. Each read then raises `NoReadableSpace`. `serve --grant` stops at the start for such a grant.
+- Each read gets the readable spaces again. A removed role or a revoked grant stops the next read.
+- `search`, `get_concept` and `neighbours` give the same results as the tools `search_knowledge`, `get_concept` and `concept_neighbours`. Each hit gives its `space`.
+- Each refused read writes the line in the audit log that the server writes, with the name of the matching tool as the action.
+- `data_dir=` replaces the data directory. `env=` gives the `CURU_MEMORY_*` variables as a dictionary, for example the embedder settings of [Search by meaning](#search-by-meaning). With no `env`, the library reads the environment of the process.
+- The library does not use `CURU_MEMORY_PRINCIPAL` to select the principal. A value that is not a valid handle raises `ConfigError`.
+- The principal is not a security boundary in one process. The boundary is who can read the data directory.
+
+Each error is in `curu_memory`:
+
+| Call | Cause | Error |
+|---|---|---|
+| `build_space` | The concept directory does not exist, or the space name is not valid. `details.field` names the argument. | `InvalidArgument` |
+| `build_space` | Another index run holds the lock. | `IndexLocked` |
+| `build_space` | The embedder model is not the model of another space. | `IndexRefused` |
+| `build_space` | The embedder failed. The old index stays. | `EmbedderFailed` |
+| `build_space`, `open_knowledge` | A `CURU_MEMORY_*` variable is not valid. | `ConfigError` |
+| `open_knowledge` | No person has the handle, or `person` and `grant` are both given. | `InvalidArgument` |
+| each read | The principal can read no space. | `NoReadableSpace` |
+| `get_concept`, `neighbours` | No readable space holds the concept. | `ConceptNotFound` |
+| `search` | The question is empty or too long, or the limit is not from 1 to 50. | `InvalidArgument` |
+| each read | No readable space has an index. | `IndexMissing` |
+
+Each error except `IndexLocked` and `ConfigError` is a `CuruMemoryError`. Its `code` is the code that a tool gives, for example `concept_not_found`.
 
 ## Limits
 
-- On stdio, in the browser and with the static token, one process reads as one person (`CURU_MEMORY_PRINCIPAL`). On stdio, `serve --grant` makes the process read as the agent of one grant. Only the OIDC mode of HTTP gives each request its own person or agent.
+- On stdio, in the browser and with the static token, one process reads as one person (`CURU_MEMORY_PRINCIPAL`). In Python, each `Knowledge` reads as the principal of its `open_knowledge`. On stdio, `serve --grant` makes the process read as the agent of one grant. Only the OIDC mode of HTTP gives each request its own person or agent.
 - There is no encryption at rest yet.
 - The browser has no OIDC login.
 - Agents and persons cannot write knowledge through curu-memory yet. Edit the concept files, then run the index command.
@@ -609,7 +638,7 @@ The `curu-memory` command uses these exit codes:
 - A match between a question in words and a clip needs 0.68 or more with EmbeddingGemma 2. The limit comes from speech clips. Speech test clips scored from 0.73 with their own questions. Wrong clips and unrelated questions reached 0.64. Music and sound effects can score lower.
 - The index holds a copy of each media file. One hundred files of 2 MB make the index about 200 MB larger.
 - There is no file watcher. Run the index command after each change.
-- curu-memory has no public Python API yet. Each module is internal.
+- The Python API cannot search with media, and it cannot write a concept. Use `curu-memory search --media` or the tool `search_knowledge_by_media` for media.
 
 ## Technical notes
 
@@ -628,7 +657,8 @@ The `curu-memory` command uses these exit codes:
 - The concept rules are the same as the rules of the curu index, so each curu concept file indexes here.
 - The tool contracts are in [specs/001-okf-index-mcp-search/contracts/](specs/001-okf-index-mcp-search/contracts/).
 - curu-memory uses the official MCP Python SDK. It never loads model weights.
-- curu uses curu-memory as a library, and the version range of a release follows a version policy. See [ADR-019](project-management/ADRs/ADR-019-curu-uses-curu-memory-as-a-library.md).
+- curu uses curu-memory as a library, and the version range of a release follows a version policy. See [ADR-019](project-management/ADRs/ADR-019-curu-uses-curu-memory-as-a-library.md). `tests/contract/public_api.txt` holds the names of `curu_memory.__all__`. The contract is [specs/015-the-public-library-api/contracts/public-api.md](specs/015-the-public-library-api/contracts/public-api.md).
+- The core install has `pydantic`, `httpx2`, `markdown-it-py` and `pyyaml`. The `server` extra adds `mcp`, `starlette` and `uvicorn`.
 
 ## Develop
 
@@ -639,7 +669,7 @@ uv sync
 uv run pytest
 ```
 
-The default tests need no network, no GPU and no model. They use a fake embedder and a copy of the curu concept files. The tests with a real embedder have the `integration` marker. With no GPU embedder server, start the [development embedder](#glossary) first, as [tools/embedder_server/README.md](tools/embedder_server/README.md) says. Then run:
+`uv sync` installs the `server` extra, because the development group names it. The default tests need no network, no GPU and no model. They use a fake embedder and a copy of the curu concept files. The tests with a real embedder have the `integration` marker. With no GPU embedder server, start the [development embedder](#glossary) first, as [tools/embedder_server/README.md](tools/embedder_server/README.md) says. Then run:
 
 ```bash
 CURU_MEMORY_EMBEDDER_URL=http://127.0.0.1:30000 CURU_MEMORY_EMBEDDER_TIMEOUT=300 uv run pytest -m integration
@@ -673,6 +703,7 @@ The CI runs the same gates on each pull request and on each push to `main`. A re
 - **Data URI**: a text that holds the bytes of a file in base64, with their MIME type, for example `data:image/png;base64,...`.
 - **Data directory**: the directory of the index, the embedding cache, the access store `access.sqlite` and the audit log `audit.jsonl`. The default is `~/.local/share/curu-memory`, or `$XDG_DATA_HOME/curu-memory`. `CURU_MEMORY_DATA_DIR` changes it.
 - **Development embedder**: the CPU server in `tools/embedder_server/` that serves EmbeddingGemma 2 for the integration tier.
+- **Extra**: a named set of optional packages of a Python package, for example `server` in `curu-memory[server]`.
 - **Embedder**: a server that changes a text, an image, a clip or a video into an embedding.
 - **Embedding**: a list of numbers that holds the meaning of a text, an image, a clip or a video. Items with a near meaning have near embeddings.
 - **GraphRAG**: retrieval that uses a search and the links between concepts to give an agent its context.
@@ -690,11 +721,11 @@ The CI runs the same gates on each pull request and on each push to `main`. A re
 - **Web browser**: the program that shows web pages, for example Firefox.
 - **SHA-256**: a hash of 64 hexadecimal characters that the bytes of a file give. Different bytes give a different SHA-256.
 - **Unit**: one part of a concept that has its own embedding: the summary, the overview, a `##` section, an image, a clip or a video.
-- **Version range**: the lowest version and the first version to exclude, for example `>=0.1,<0.2`.
+- **Version range**: the lowest version and the first version to exclude, for example `>=0.3,<0.4`.
 - **Space**: a part of the knowledge with its own index: `global`, `team/<slug>` or `personal/<handle>`. Each request reads only the spaces that its caller can read.
 - **Team slug**: the short name of a team in a space name, for example `look` in `team/look`.
 - **Instance owner**: a person with `admin` on `global` and on each team space. The first registered person is an instance owner.
-- **Principal**: the person or the agent of a request: from `CURU_MEMORY_PRINCIPAL`, from `serve --grant`, from the OIDC token on HTTP, or `anonymous` with no principal.
+- **Principal**: the person or the agent of a request, or `anonymous` with no principal. It comes from `CURU_MEMORY_PRINCIPAL`, `serve --grant`, the OIDC token on HTTP or `open_knowledge`.
 - **Operator**: the person who runs `curu-memory access` and `curu-memory index` on the computer of the server.
 - **Access store**: `access.sqlite`, with the persons, the teams, the members, the agents and the grants.
 - **Audit log**: `audit.jsonl`, with one line for each change of access, each refused read and each refused token.

{curu_memory-0.2.0 → curu_memory-0.3.0}/pyproject.toml

@@ -5,12 +5,18 @@ description = "A shared knowledge base and GraphRAG store for ComfyUI and genera
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.12"
+# The core: the library, `index`, `search` and `access`. No server package (spec 015).
 dependencies = [
-    "mcp==2.3.0",
     "pydantic>=2.12",
     "httpx2>=2.10",
     "markdown-it-py>=4.0",
     "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+# `serve` and `browse` need these. Install them with curu-memory[server].
+server = [
+    "mcp==2.3.0",
     "starlette>=1.0",
     "uvicorn>=0.31.1",
 ]
@@ -25,11 +31,12 @@ Changelog = "https://github.com/darth-veitcher/curu-memory/blob/main/CHANGELOG.m
 
 [dependency-groups]
 dev = [
+    # The extra itself, so that the pin of mcp has one place (research R7).
+    "curu-memory[server]",
     "pytest>=8",
     "pytest-timeout>=2.3",
     "ruff>=0.15",
     "ty>=0.0.1a20",
-    "uvicorn>=0.31.1",
 ]
 
 [build-system]

curu_memory-0.3.0/src/curu_memory/__init__.py

@@ -0,0 +1,52 @@
+"""curu-memory: a shared knowledge base for ComfyUI, served to agents over MCP.
+
+The names in `__all__` are the public Python API (ADR-019). Each other name is internal
+and can change in any release. `tests/contract/public_api.txt` holds the same names.
+"""
+
+__version__ = "0.3.0"
+
+from curu_memory.config import ConfigError  # noqa: E402
+from curu_memory.errors import (  # noqa: E402
+    ConceptNotFound,
+    CuruMemoryError,
+    EmbedderFailed,
+    IndexMissing,
+    IndexRefused,
+    InvalidArgument,
+    NoReadableSpace,
+)
+from curu_memory.indexing import IndexReport  # noqa: E402
+from curu_memory.library import Knowledge, build_space, open_knowledge  # noqa: E402
+from curu_memory.ports import IndexLocked  # noqa: E402
+from curu_memory.retrieval import (  # noqa: E402
+    ConceptDetail,
+    MediaItem,
+    Neighbour,
+    Neighbours,
+    SearchHit,
+    SearchResult,
+)
+
+__all__ = [
+    "ConceptDetail",
+    "ConceptNotFound",
+    "ConfigError",
+    "CuruMemoryError",
+    "EmbedderFailed",
+    "IndexLocked",
+    "IndexMissing",
+    "IndexRefused",
+    "IndexReport",
+    "InvalidArgument",
+    "Knowledge",
+    "MediaItem",
+    "Neighbour",
+    "Neighbours",
+    "NoReadableSpace",
+    "SearchHit",
+    "SearchResult",
+    "__version__",
+    "build_space",
+    "open_knowledge",
+]