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

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

@@ -4,6 +4,29 @@ All notable changes to this project are in this file. The format follows [Keep a
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-11-01
+
+### Added
+
+- `validate(path)` in `curu_memory.__all__`: the faults of a concept file or a directory, with the rules of the index command. Each `OkfFault` has `path`, `line` and `message`.
+- `OKF_VERSION`, `LINK_KINDS` and `conformance_fixtures()` in `curu_memory.__all__`. The package ships `okf_v0_2/schema.json`, a JSON Schema of the front matter, and valid and invalid conformance fixtures with their expected faults.
+- ADR-020: the copy of the curu concepts is a frozen evaluation corpus, not a reference of the format.
+- `TOOL_SCHEMA_VERSION` in `curu_memory.__all__`: the version of the MCP tool schemas and the error codes. It is 1 for the tools of 0.3.0.
+- `tests/contract/tool_schemas.json` and `tools/tool_schemas.py`. A test fails when a tool, a field or an error code changes and `TOOL_SCHEMA_VERSION` does not go up. A changed description needs no new version.
+
+## [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 → curu_memory-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: curu-memory
-Version: 0.2.0
+Version: 0.4.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
@@ -10,11 +10,12 @@ 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
+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
@@ -28,6 +29,7 @@ curu-memory is a shared knowledge base for ComfyUI and generative media. It read
 | Task | Command | Section |
 |---|---|---|
 | Write a concept for the index | Add `<name>.md` with front matter | [Write a concept file](#write-a-concept-file) |
+| Check concept files before you index them | `curu_memory.validate("knowledge")` | [Check concept files](#check-concept-files) |
 | Add images, audio and video to a concept | Add a `media:` list to the front matter | [Add media to a concept](#add-media-to-a-concept) |
 | Build the index from your concept files | `curu-memory index --concepts ./knowledge` | [Index your knowledge](#index-your-knowledge) |
 | Keep team notes and personal notes apart from the global knowledge | `curu-memory index --space personal/me` | [Keep team and personal knowledge apart](#keep-team-and-personal-knowledge-apart) |
@@ -42,24 +44,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.4,<0.5"
 ```
 
-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
 
@@ -119,6 +122,25 @@ A concept file is a Markdown file with YAML front matter between two `---` lines
 - A link resolves by file name in all the subdirectories, so two concept files must not have the same name.
 - Write each `##` heading for one topic. Search by meaning compares each section separately.
 
+### Check concept files
+
+Check a file or a directory before you index it. The check uses the rules of the index command, and it writes nothing.
+
+```python
+import curu_memory
+
+for fault in curu_memory.validate("knowledge"):
+    print(fault.path, fault.line, fault.message)
+```
+
+- `validate` gives a list of [faults](#glossary). An empty list means that the index command indexes each file of the directory, unless an identifier is also in another space.
+- `path` is relative to the directory that you give. For one file, it is the file name. `line` counts from the first `---` line, and it is None when the fault has no line. `message` is the reason that the index command reports.
+- A warning of the index command is not a fault, for example a missing `type` or a link to a missing concept.
+- A Markdown link in a code block still needs a link kind. A wiki-link `[[...]]` in code is text.
+- `curu_memory.LINK_KINDS` holds the link kinds. `curu_memory.OKF_VERSION` is `0.2`, the version of the format.
+- The package ships the format: `schema.json`, a JSON Schema of the front matter, and conformance fixtures. `curu_memory.conformance_fixtures()` gives the directory of the fixtures. Its parent directory holds `schema.json`.
+- To test a parser in another language, give it each file of `valid/` and of `invalid/`. Compare its faults with `expected.toml`.
+
 ### Add media to a concept
 
 Add example outputs, reference images, audio clips or videos to a concept with a `media` list. Each path is relative to the concept file:
@@ -587,11 +609,59 @@ 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. `validate` and `TOOL_SCHEMA_VERSION` start with 0.4.0, so a program pins `curu-memory>=0.4,<0.5`.
+
+```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` |
+| `validate` | The path does not exist. `details.field` is `path`. | `InvalidArgument` |
+| `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 +679,8 @@ 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.
+- `validate` does not read the index, so it does not find an identifier that is also in another space. For one file, it does not find a duplicate identifier.
+- 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
 
@@ -625,10 +696,13 @@ The `curu-memory` command uses these exit codes:
 - The plan for keys and encryption of private knowledge is [ADR-002](project-management/ADRs/ADR-002-server-held-envelope-keys.md).
 - The word match uses SQLite FTS5 (the full-text search of SQLite) with the `unicode61` tokenizer (the rule that splits a text into words). The tokenizer keeps `.`, `_` and `-` in a word. A word of three or more characters also matches as a prefix.
 - Search fuses the two rankings with reciprocal rank fusion, with k = 60. The lower of the two values counts one tenth. So ten rivals that are a little worse in both rankings do not push out the best answer of one ranking. See [ADR-006](project-management/ADRs/ADR-006-damped-rank-fusion.md). The identifier breaks a tie, so the order is stable.
-- The concept rules are the same as the rules of the curu index, so each curu concept file indexes here.
+- The concept rules are the same as the rules of the curu index, so each curu concept file indexes here. The index command and `validate` use one implementation of them. The schema and the fixtures are in `src/curu_memory/okf_v0_2/`. See [specs/017-the-okf-v0-2-schema/contracts/okf.md](specs/017-the-okf-v0-2-schema/contracts/okf.md). The copy of the curu concepts in `tests/fixtures/eval_corpus/` is a frozen evaluation corpus, not a reference of the format. See [ADR-020](project-management/ADRs/ADR-020-a-frozen-evaluation-corpus.md).
 - 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`.
+- `curu_memory.TOOL_SCHEMA_VERSION` is the version of the MCP tool schemas and the error codes. The value is 1 for the tools of 0.3.0. It goes up by 1 in each pull request that changes a tool, a field or an error code. A change of a description or a title does not change it. It is not the package version.
+- A Python program that imports `curu_memory` can compare `TOOL_SCHEMA_VERSION` with the version that it expects. A different value means that a tool, a field or an error code is different. The MCP server does not send the value. `tests/contract/tool_schemas.json` holds the schemas of the current version.
 
 ## Develop
 
@@ -639,7 +713,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 the frozen evaluation corpus in `tests/fixtures/eval_corpus/`, a copy of 183 curu concept files. The corpus is for the search measurements only. The shipped fixtures are the reference of the format. 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,10 +747,15 @@ 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.
+- **Conformance fixtures**: the valid and invalid concept files that the package ships, with the expected faults in `expected.toml`.
+- **Evaluation corpus**: the frozen copy of 183 curu concept files in `tests/fixtures/eval_corpus/`, for the search measurements.
+- **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.
+- **Fault**: one problem that makes the index command skip a concept file. `validate` gives each fault with its `path`, `line` and `message`.
 - **GraphRAG**: retrieval that uses a search and the links between concepts to give an agent its context.
 - **Index**: the searchable copy of the concept files that the index command makes.
+- **JSON Schema**: a standard JSON document that gives the fields and the types of a JSON or YAML value.
 - **Link kind**: the type of a link between two concepts, for example `USES_COMPONENT`.
 - **MCP**: the Model Context Protocol, which lets an agent find and call tools.
 - **Minor version**: the second number of `X.Y.Z`. Below 1.0, a new minor version can remove or change a name or a tool field.
@@ -687,14 +766,15 @@ The CI runs the same gates on each pull request and on each push to `main`. A re
 - **Task prompt**: a fixed text that curu-memory puts around a question or a section before it sends the text to the embedder.
 - **Stdio**: the standard input and output of a process. A local MCP client talks to the server through them.
 - **Streamable HTTP**: the MCP transport over HTTP, for remote agents.
+- **Wiki-link**: a link of the form `[[name]]`. OKF does not accept it outside code.
 - **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.4,<0.5`.
 - **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.4.0}/README.md

@@ -9,6 +9,7 @@ curu-memory is a shared knowledge base for ComfyUI and generative media. It read
 | Task | Command | Section |
 |---|---|---|
 | Write a concept for the index | Add `<name>.md` with front matter | [Write a concept file](#write-a-concept-file) |
+| Check concept files before you index them | `curu_memory.validate("knowledge")` | [Check concept files](#check-concept-files) |
 | Add images, audio and video to a concept | Add a `media:` list to the front matter | [Add media to a concept](#add-media-to-a-concept) |
 | Build the index from your concept files | `curu-memory index --concepts ./knowledge` | [Index your knowledge](#index-your-knowledge) |
 | Keep team notes and personal notes apart from the global knowledge | `curu-memory index --space personal/me` | [Keep team and personal knowledge apart](#keep-team-and-personal-knowledge-apart) |
@@ -23,24 +24,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.4,<0.5"
 ```
 
-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
 
@@ -100,6 +102,25 @@ A concept file is a Markdown file with YAML front matter between two `---` lines
 - A link resolves by file name in all the subdirectories, so two concept files must not have the same name.
 - Write each `##` heading for one topic. Search by meaning compares each section separately.
 
+### Check concept files
+
+Check a file or a directory before you index it. The check uses the rules of the index command, and it writes nothing.
+
+```python
+import curu_memory
+
+for fault in curu_memory.validate("knowledge"):
+    print(fault.path, fault.line, fault.message)
+```
+
+- `validate` gives a list of [faults](#glossary). An empty list means that the index command indexes each file of the directory, unless an identifier is also in another space.
+- `path` is relative to the directory that you give. For one file, it is the file name. `line` counts from the first `---` line, and it is None when the fault has no line. `message` is the reason that the index command reports.
+- A warning of the index command is not a fault, for example a missing `type` or a link to a missing concept.
+- A Markdown link in a code block still needs a link kind. A wiki-link `[[...]]` in code is text.
+- `curu_memory.LINK_KINDS` holds the link kinds. `curu_memory.OKF_VERSION` is `0.2`, the version of the format.
+- The package ships the format: `schema.json`, a JSON Schema of the front matter, and conformance fixtures. `curu_memory.conformance_fixtures()` gives the directory of the fixtures. Its parent directory holds `schema.json`.
+- To test a parser in another language, give it each file of `valid/` and of `invalid/`. Compare its faults with `expected.toml`.
+
 ### Add media to a concept
 
 Add example outputs, reference images, audio clips or videos to a concept with a `media` list. Each path is relative to the concept file:
@@ -568,11 +589,59 @@ 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. `validate` and `TOOL_SCHEMA_VERSION` start with 0.4.0, so a program pins `curu-memory>=0.4,<0.5`.
+
+```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` |
+| `validate` | The path does not exist. `details.field` is `path`. | `InvalidArgument` |
+| `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 +659,8 @@ 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.
+- `validate` does not read the index, so it does not find an identifier that is also in another space. For one file, it does not find a duplicate identifier.
+- 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
 
@@ -606,10 +676,13 @@ The `curu-memory` command uses these exit codes:
 - The plan for keys and encryption of private knowledge is [ADR-002](project-management/ADRs/ADR-002-server-held-envelope-keys.md).
 - The word match uses SQLite FTS5 (the full-text search of SQLite) with the `unicode61` tokenizer (the rule that splits a text into words). The tokenizer keeps `.`, `_` and `-` in a word. A word of three or more characters also matches as a prefix.
 - Search fuses the two rankings with reciprocal rank fusion, with k = 60. The lower of the two values counts one tenth. So ten rivals that are a little worse in both rankings do not push out the best answer of one ranking. See [ADR-006](project-management/ADRs/ADR-006-damped-rank-fusion.md). The identifier breaks a tie, so the order is stable.
-- The concept rules are the same as the rules of the curu index, so each curu concept file indexes here.
+- The concept rules are the same as the rules of the curu index, so each curu concept file indexes here. The index command and `validate` use one implementation of them. The schema and the fixtures are in `src/curu_memory/okf_v0_2/`. See [specs/017-the-okf-v0-2-schema/contracts/okf.md](specs/017-the-okf-v0-2-schema/contracts/okf.md). The copy of the curu concepts in `tests/fixtures/eval_corpus/` is a frozen evaluation corpus, not a reference of the format. See [ADR-020](project-management/ADRs/ADR-020-a-frozen-evaluation-corpus.md).
 - 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`.
+- `curu_memory.TOOL_SCHEMA_VERSION` is the version of the MCP tool schemas and the error codes. The value is 1 for the tools of 0.3.0. It goes up by 1 in each pull request that changes a tool, a field or an error code. A change of a description or a title does not change it. It is not the package version.
+- A Python program that imports `curu_memory` can compare `TOOL_SCHEMA_VERSION` with the version that it expects. A different value means that a tool, a field or an error code is different. The MCP server does not send the value. `tests/contract/tool_schemas.json` holds the schemas of the current version.
 
 ## Develop
 
@@ -620,7 +693,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 the frozen evaluation corpus in `tests/fixtures/eval_corpus/`, a copy of 183 curu concept files. The corpus is for the search measurements only. The shipped fixtures are the reference of the format. 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,10 +727,15 @@ 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.
+- **Conformance fixtures**: the valid and invalid concept files that the package ships, with the expected faults in `expected.toml`.
+- **Evaluation corpus**: the frozen copy of 183 curu concept files in `tests/fixtures/eval_corpus/`, for the search measurements.
+- **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.
+- **Fault**: one problem that makes the index command skip a concept file. `validate` gives each fault with its `path`, `line` and `message`.
 - **GraphRAG**: retrieval that uses a search and the links between concepts to give an agent its context.
 - **Index**: the searchable copy of the concept files that the index command makes.
+- **JSON Schema**: a standard JSON document that gives the fields and the types of a JSON or YAML value.
 - **Link kind**: the type of a link between two concepts, for example `USES_COMPONENT`.
 - **MCP**: the Model Context Protocol, which lets an agent find and call tools.
 - **Minor version**: the second number of `X.Y.Z`. Below 1.0, a new minor version can remove or change a name or a tool field.
@@ -668,14 +746,15 @@ The CI runs the same gates on each pull request and on each push to `main`. A re
 - **Task prompt**: a fixed text that curu-memory puts around a question or a section before it sends the text to the embedder.
 - **Stdio**: the standard input and output of a process. A local MCP client talks to the server through them.
 - **Streamable HTTP**: the MCP transport over HTTP, for remote agents.
+- **Wiki-link**: a link of the form `[[name]]`. OKF does not accept it outside code.
 - **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.4,<0.5`.
 - **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.4.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]
@@ -57,8 +64,9 @@ include = [
 [tool.ruff]
 line-length = 100
 target-version = "py312"
-# The fixture corpora are copies of real concept files. They must stay byte for byte.
-extend-exclude = ["tests/fixtures"]
+# The fixture corpora are copies of real concept files, and the OKF fixtures hold a
+# file that is not UTF-8 on purpose. They must stay byte for byte.
+extend-exclude = ["tests/fixtures", "src/curu_memory/okf_v0_2/fixtures"]
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "UP", "B", "SIM", "ASYNC"]

curu_memory-0.4.0/src/curu_memory/__init__.py

@@ -0,0 +1,68 @@
+"""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.4.0"
+#: The version of the MCP tool schemas and error codes. It goes up by 1 for each change
+#: of `tests/contract/tool_schemas.json` (ADR-019). It is not the package version.
+TOOL_SCHEMA_VERSION = 1
+
+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.okf import (  # noqa: E402
+    LINK_KINDS,
+    OKF_VERSION,
+    OkfFault,
+    conformance_fixtures,
+    validate,
+)
+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",
+    "LINK_KINDS",
+    "MediaItem",
+    "Neighbour",
+    "Neighbours",
+    "NoReadableSpace",
+    "OKF_VERSION",
+    "OkfFault",
+    "SearchHit",
+    "SearchResult",
+    "TOOL_SCHEMA_VERSION",
+    "__version__",
+    "build_space",
+    "conformance_fixtures",
+    "open_knowledge",
+    "validate",
+]