graphiti-local 0.4.0__tar.gz

graphiti_local-0.4.0/.dockerignore

@@ -0,0 +1,10 @@
+*
+!Dockerfile
+!pyproject.toml
+!uv.lock
+!README.md
+!src
+!src/**
+!config
+!config/ollama.example.yaml
+**/__pycache__

graphiti_local-0.4.0/.env.example

@@ -0,0 +1,7 @@
+# Copy to .env only if your launcher loads dotenv files.
+# The YAML examples reference these variables directly.
+OPENAI_API_KEY=
+FALKORDB_PASSWORD=
+NEO4J_PASSWORD=
+KG_WORKSPACE_DIR=./workspace
+

graphiti_local-0.4.0/.github/ISSUE_TEMPLATE/setup-result.yml

@@ -0,0 +1,39 @@
+name: Local setup result
+description: Share a successful setup or the step where you got stuck.
+title: "Setup result: "
+labels: []
+body:
+  - type: dropdown
+    id: result
+    attributes:
+      label: Result
+      options:
+        - Reached a synthetic query result
+        - Reached a synthetic MCP query result
+        - Blocked during setup
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, architecture, memory, Python and Ollama versions. No device identifiers.
+    validations:
+      required: true
+  - type: input
+    id: models
+    attributes:
+      label: Models and repository version
+      placeholder: qwen2.5:7b; nomic-embed-text; v0.4.0
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Synthetic result or failing step
+      description: Paste the relevant command and synthetic output. Remove credentials, home paths, and private graph data.
+    validations:
+      required: true
+  - type: input
+    id: source
+    attributes:
+      label: Where did you find the project?
+      description: Optional; for example GitHub, a gist, or an MCP directory.

graphiti_local-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv sync --extra dev
+      - run: uv run ruff check .
+      - run: uv run pytest
+      - run: uv run python scripts/release_audit.py . --allow-remote --identity-base origin/main

graphiti_local-0.4.0/.github/workflows/container.yml

@@ -0,0 +1,26 @@
+name: Container MCP smoke
+on:
+  push:
+    paths:
+      - Dockerfile
+      - .dockerignore
+      - pyproject.toml
+      - uv.lock
+      - src/**
+      - config/ollama.example.yaml
+      - scripts/mcp_smoke.py
+      - .github/workflows/container.yml
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  discovery:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv sync --frozen
+      - run: docker build -t graphiti-local-smoke .
+      - run: uv run --frozen python scripts/mcp_smoke.py docker run --rm -i graphiti-local-smoke

graphiti_local-0.4.0/.gitignore

@@ -0,0 +1,16 @@
+.DS_Store
+.env
+.venv/
+__pycache__/
+*.egg-info/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+coverage.xml
+htmlcov/
+workspace/
+*.ladybug
+*.lbug
+

graphiti_local-0.4.0/CHANGELOG.md

@@ -0,0 +1,209 @@
+# Changelog
+
+## 0.4.0
+
+This release makes the review boundary apply to model extraction itself, makes current
+facts the safe retrieval default, and hardens the local and HTTP deployment paths.
+
+### Breaking
+
+- `kg ask` and `search_memory_facts` now suppress facts whose `invalid_at` timestamp
+  has passed. Use `kg ask --history` or `include_invalidated: true` for an intentional
+  historical query.
+- Version 2 exports are canonical, atomic, and carry a record count and SHA-256 digest.
+  Restore verifies them before opening a writer. Version 1 snapshots remain readable.
+- A Ladybug HTTP deployment cannot configure a token for only some groups. Ladybug is
+  one embedded graph and cannot enforce that boundary; use a full-graph token or a
+  server backend when per-group isolation is required.
+
+### Added
+
+- `kg-ingest INPUT --review-output SNAPSHOT` extracts into a disposable Ladybug graph
+  and exports the exact resolved nodes, edges, and episodes for review. The configured
+  production graph is never opened. The command prints the restore invocation that
+  promotes the reviewed snapshot without running extraction again.
+- Streamable HTTP accepts named `server.auth.tokens`, each bound to an enforced group
+  list. Multiple tokens may overlap during rotation. The existing `auth.token` and
+  `auth.groups` form remains supported.
+- Fact retrieval overfetches the configured candidate multiple, applies the selected
+  cross encoder after RRF, preserves separate UUIDs when facts have identical text,
+  filters on the final score, and returns the score and ranker with each result.
+- `llm.api_mode` explicitly selects `responses`, `chat`, or endpoint-based `auto` mode.
+  `llm.max_tokens` is enforced as a hard ceiling even when an extraction prompt asks
+  the upstream client for a larger output.
+- Every Ladybug write path shares a cross-process lock with a configurable timeout,
+  including ingest, workspace drain, restore, setup, and review staging.
+- `kg-demo` answers against a packaged synthetic graph in one command, without a model
+  server or database setup. `kg ask --keyword` and `kg nodes --keyword` provide the
+  same model-free retrieval path for an existing graph.
+- A Docker image and MCP discovery container workflow validate the packaged server and
+  its six-tool read-only surface.
+- `server.json` describes the PyPI stdio package for publication in the official MCP
+  Registry.
+
+### Fixed
+
+- FalkorDB search removes only a reserved standalone underscore token. Multi-label node
+  searches run one compatible query per label and merge UUIDs, avoiding invalid
+  RediSearch label expressions while preserving identifiers such as `foo_bar`.
+- Export now fails closed and names the record kind when a backend cannot collect it,
+  instead of producing a plausible partial snapshot.
+- Extraction and restore failures include the operation and exception type, including
+  a useful fallback for exceptions with an empty message.
+- The release audit checks unpublished commits against the fetched default branch, so
+  historical public metadata does not make every later release fail while new private
+  author identities remain blocked.
+- The release's CLI and demo changes pass the configured Ruff gate.
+
+## 0.3.0
+
+0.2.x could run unattended, but not on the fully local profile: on Ladybug every search
+failed, and a running server locked every other command out of the file. This release
+makes the embedded backend hold up under the same rules as the server backends, and it
+closes the loop that `kg export` opened.
+
+### Breaking
+
+- **graphiti-core is pinned to 0.30.1** (was 0.29.3). Upstream fixes that reach every
+  user: node attributes are no longer cleared when no entity type applies, the edge
+  reranker shortlist is merged correctly, and Neo4j queries go to the configured
+  database. Neo4j Enterprise users with a renamed home database: read the upstream
+  0.30.0 notes, queries now target `neo4j` unless `database` is set.
+- **Readers open Ladybug read-only and require a prepared database.** `graphiti-local`,
+  `kg ask`, `kg export`, `kg verify` and the other read commands no longer take the
+  write lock, so an ingest or a drain runs while the server is up. They refuse to open a
+  file without the full-text indexes and name the fix. Existing databases: run
+  `kg-ladybug-setup --database PATH --apply` once; it creates the missing indexes and
+  does not touch the data.
+- **A write refuses an embedder change.** The first ingest or restore records the
+  embedder for its database in `workspace/embedders.json`. A later `kg-ingest`,
+  `kg-workspace drain` or restore with a different `embedder.model` or width exits `2`
+  instead of mixing two vector spaces in one graph. To move to a new embedder:
+  `kg export`, an empty database, `kg-ingest SNAPSHOT --restore --apply`.
+- **`kg` exits `3` when a graph call exceeds `graph.query_timeout_seconds`** (default
+  30). The MCP tools return an error object for the same case.
+
+### Added
+
+- `kg-ingest SNAPSHOT --restore [--group G] [--apply]` replays a `kg export` snapshot
+  into the configured backend: entity names and facts are re-embedded under the
+  configured embedder, nodes are saved before the edges that reference them, and records
+  keep their UUIDs, so a second restore updates rather than duplicates. An edge whose
+  endpoint is not in the graph is reported as failed, not silently skipped. `--group`
+  remaps every record, which is how a Ladybug snapshot lands on FalkorDB or Neo4j.
+- `kg duplicates [group ...]` lists entities whose names collide once casing, whitespace
+  and punctuation are ignored, with UUIDs and summaries. Read-only; a merge is a
+  proposal like any other correction.
+- `graph.query_timeout_seconds` bounds every graph call in the CLI, the six MCP tools and
+  `kg verify`. A backend that hangs produces an error an agent can read instead of a
+  tool call that never returns.
+- The MCP server reopens its read-only Ladybug handle when the file changes, so facts
+  landed by a drain are served without a restart.
+- `server.allowed_hosts` for `streamable-http` behind a reverse proxy: the Host names the
+  MCP SDK's DNS-rebinding check accepts. Without it the SDK default applies, which is
+  loopback names only on a loopback host and no check elsewhere.
+- `kg --version`, and `-H`/`--human` is accepted after the subcommand as well as before
+  it (`kg verify --offline -H`).
+- `kg doctor` reports the installed versions, the recorded embedder for the configured
+  database, and whether a Ladybug file has its extensions and full-text indexes.
+- `kg-ladybug-setup --apply` creates the schema and the four full-text indexes as well as
+  installing the extensions, so a fresh database answers `kg ask` before anything is
+  ingested.
+
+### Fixed
+
+- Every search on a Ladybug graph raised `Binder exception: Table RelatesToNode_ doesn't
+  have an index with name edge_name_and_fact` (#1). graphiti-core's Kuzu driver declares
+  its full-text indexes but its index builder is a no-op, so they were never created;
+  the edgeless graph in the report was a symptom. Read-write opens and the setup command
+  create them now, and an empty graph returns no facts.
+- `kg-workspace drain` and `kg-ingest` report a refused write or a backend that did not
+  open as an error with an exit code instead of a traceback.
+- `__version__` reported 0.1.0 whatever the release; it comes from the package metadata.
+- The release audit flagged GitHub's own noreply committer identity on the merge commit
+  a pull request run checks out, so every pull request failed CI while the same commit
+  passed on push. GitHub's noreply identities are treated as share-safe; the check now
+  covers committer identities as well as authors.
+
+## 0.2.2
+
+- `kg-ingest` handles `SIGTERM` and `SIGINT`: it finishes the record in flight, closes
+  the driver, and reports `interrupted: true` so a re-run continues from the ledger.
+  Previously a wrapped `timeout` killed the process mid-write. On the embedded Ladybug
+  backend that could leave a partial write the database then refused to reopen
+  (`Storage exception: Checksum verification failed, the WAL file is corrupted`), which
+  took out every later read as well. This was found by an end-to-end run, not in review.
+
+  A signal cannot save you from `SIGKILL` or a power cut. Take a snapshot with
+  `kg export` before a long ingest into an embedded backend.
+
+## 0.2.1
+
+- `kg doctor` gains an `embedding-dim-binding` check. graphiti reads `EMBEDDING_DIM`
+  from the environment once, at import time, and uses that constant to build zero
+  vectors during search. If anything imports graphiti before the value is set, searches
+  are built at the wrong width while the embedder returns the right one, and nothing
+  reports it. The check compares the constant graphiti actually resolved against
+  `embedder.dimensions`. This matters most on the local profile, where
+  `nomic-embed-text` is 768 and graphiti's own default is 1024.
+- The export header no longer implies an import command exists; embeddings are omitted
+  because they are derived from the text under whichever embedder is in use.
+
+## 0.2.0 — Runs unattended
+
+v0.1.0 was read-first and human-gated, but it assumed a human at the keyboard: output
+was decorated text, a refused write still exited 0, configuration errors surfaced as
+tracebacks mid-run, and a half-finished ingest could not resume. This release makes the
+tool safe to hand to a cron job or an agent.
+
+### Breaking
+
+- **`kg` prints JSON on stdout by default.** Pass `-H`/`--human` for the previous
+  reader-friendly output. Failures now go to stderr and never appear on stdout as a
+  success-shaped object.
+- **`kg propose` enforces the group allow-list.** A fact addressed to a group that
+  `graph.groups` does not declare is refused with exit code `2` and is not queued.
+  Reads always enforced this; the write path did not.
+- **`server.transport: streamable-http` requires `server.auth.token`** (16 characters
+  or more). An unauthenticated network transport exposed every configured group.
+- **A known embedding model whose width disagrees with `embedder.dimensions` is now a
+  configuration error.** For example `nomic-embed-text` with `1536`. The mismatch was
+  previously silent and corrupted every embedding it wrote.
+- `kg-ingest` and `kg-workspace` also default to JSON and accept `-H`.
+
+### Added
+
+- `kg doctor [--offline]` — preflight for configuration, workspace, backend, LLM and
+  embedder. The embedder check calls the live endpoint and compares the real vector
+  width against the configured one.
+- `kg verify [--offline]` — asserts the six read tools are registered, that no write
+  tool is exposed (a negative control), and that live retrieval works. Run it before
+  and after any model, config or backend change.
+- `kg export [group ...] [--output PATH]` — a backend-independent JSONL snapshot
+  written from the graphiti models. Embeddings are omitted because they are derived
+  from the text and restoring them under a different model would be silently wrong.
+- `reranker:` configuration with `passthrough` (default, no extra model call), `bge`
+  (local, `uv sync --extra rerank`), `openai` and `gemini`. Upstream ships these
+  cross-encoders; there was previously no way to select one.
+- `config/ollama.example.yaml` — a fully local profile: local model, local embedder,
+  embedded Ladybug backend, no API key.
+- Resumable ingestion: every applied record is recorded in a content-keyed ledger, so
+  re-running a file ingests only what has not landed. `--no-resume` ignores the ledger.
+- Per-record fault isolation in ingestion: one failing episode no longer costs the
+  batch. Failures are reported and set a non-zero exit code. `--fail-fast` restores the
+  previous behaviour. `--skip-invalid` tolerates malformed input lines.
+
+### Fixed
+
+- `kg-workspace drain` archived a proposal even when its ingestion did not succeed,
+  which lost the proposal. It now archives only what landed and leaves the rest
+  approved for the next drain.
+- The proposal queue rejected group names that `graph.groups` accepts (it required
+  lowercase and disallowed dots). A configurable group is now always proposable.
+- `kg doctor` reports the resolved absolute Ladybug path; a relative path is read from
+  the working directory, which is rarely what the reader assumes.
+
+## 0.1.0
+
+Initial standalone release: six read-only MCP tools, the `kg` CLI, explicit dry-run
+ingestion, and the human-gated proposal queue.

graphiti_local-0.4.0/Dockerfile

@@ -0,0 +1,19 @@
+# Stdio discovery image for MCP directory evaluation; no private graph is copied.
+FROM ghcr.io/astral-sh/uv:0.12.13 AS uv
+FROM python:3.12-slim
+COPY --from=uv /uv /usr/local/bin/uv
+WORKDIR /app
+COPY pyproject.toml uv.lock README.md ./
+COPY src ./src
+COPY config/ollama.example.yaml ./config/ollama.example.yaml
+RUN uv sync --frozen --no-dev \
+    && useradd --create-home --uid 10001 mcp \
+    && mkdir /data \
+    && chown mcp:mcp /data
+ENV PATH="/app/.venv/bin:$PATH" \
+    GRAPHITI_LOCAL_CONFIG=/app/config/ollama.example.yaml \
+    KG_WORKSPACE_DIR=/data \
+    KG_LADYBUG_PATH=/data/graph.ladybug
+USER mcp
+RUN kg-ladybug-setup --database /data/graph.ladybug --apply
+ENTRYPOINT ["graphiti-local"]

graphiti_local-0.4.0/LICENSE

@@ -0,0 +1,160 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made
+available under the License, as indicated by a copyright notice that is included
+in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version
+of the Work and any modifications or additions to that Work or Derivative Works
+thereof, that is intentionally submitted to Licensor for inclusion in the Work
+by the copyright owner or by an individual or Legal Entity authorized to submit
+on behalf of the copyright owner. For the purposes of this definition,
+"submitted" means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems, and
+issue tracking systems that are managed by, or on behalf of, the Licensor for
+the purpose of discussing and improving the Work, but excluding communication
+that is conspicuously marked or otherwise designated in writing by the copyright
+owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of
+whom a Contribution has been received by Licensor and subsequently incorporated
+within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or Object
+form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License,
+each Contributor hereby grants to You a perpetual, worldwide, non-exclusive,
+no-charge, royalty-free, irrevocable (except as stated in this section) patent
+license to make, have made, use, offer to sell, sell, import, and otherwise
+transfer the Work, where such license applies only to those patent claims
+licensable by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s) with the Work
+to which such Contribution(s) was submitted. If You institute patent litigation
+against any entity (including a cross-claim or counterclaim in a lawsuit)
+alleging that the Work or a Contribution incorporated within the Work
+constitutes direct or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate as of the date
+such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of
+this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from the
+Source form of the Work, excluding those notices that do not pertain to any part
+of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then
+any Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if provided along
+with the Derivative Works; or, within a display generated by the Derivative
+Works, if and wherever such third-party notices normally appear. The contents of
+the NOTICE file are for informational purposes only and do not modify the
+License. You may add Your own attribution notices within Derivative Works that
+You distribute, alongside or as an addendum to the NOTICE text from the Work,
+provided that such additional attribution notices cannot be construed as
+modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a whole,
+provided Your use, reproduction, and distribution of the Work otherwise
+complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein shall
+supersede or modify the terms of any separate license agreement you may have
+executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied, including, without limitation, any warranties
+or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to in
+writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any character
+arising as a result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill, work stoppage,
+computer failure or malfunction, or any and all other commercial damages or
+losses), even if such Contributor has been advised of the possibility of such
+damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or
+Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations
+and/or rights consistent with this License. However, in accepting such
+obligations, You may act only on Your own behalf and on Your sole responsibility,
+not on behalf of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability incurred by, or
+claims asserted against, such Contributor by reason of your accepting any such
+warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+

graphiti_local-0.4.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.5
+Name: graphiti-local
+Version: 0.4.0
+Summary: A local-first temporal knowledge graph with a read-only MCP server and CLI
+License: Apache-2.0
+License-File: LICENSE
+Keywords: falkordb,graphiti,knowledge-graph,ladybugdb,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: <4,>=3.10
+Requires-Dist: filelock<4,>=3.16
+Requires-Dist: graphiti-core[falkordb]==0.30.1
+Requires-Dist: ladybug<1,>=0.19.1
+Requires-Dist: mcp<2,>=1.27
+Requires-Dist: pydantic<3,>=2.11
+Requires-Dist: pyyaml<7,>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio<1,>=0.26; extra == 'dev'
+Requires-Dist: pytest<9,>=8.3; extra == 'dev'
+Requires-Dist: ruff<1,>=0.12; extra == 'dev'
+Provides-Extra: rerank
+Requires-Dist: sentence-transformers<6,>=3.2.1; extra == 'rerank'
+Description-Content-Type: text/markdown
+
+![Graphiti Local](assets/graphiti-local-logo.png)
+
+# Graphiti Local
+
+**Local memory for your agents. You approve what they learn.**
+
+Retrieve project decisions through six read-only MCP tools or the `kg` CLI.
+Proposed updates stay in a separate queue until a human approves and applies them.
+Ollama handles local inference; embedded LadybugDB stores the graph. No Docker or
+cloud API key is needed for the local setup.
+
+![42-second synthetic memory demo](assets/local-memory-demo.gif)
+
+*Captured output excerpts with pauses condensed. [Measured results and limitations](docs/local-demo-results.md).*
+
+## Try it in one command
+
+```bash
+uvx --from git+https://github.com/renezander030/graphiti-local kg-demo
+```
+
+Answers a question against a small synthetic graph shipped with the package. No Ollama,
+no model downloads, no database setup: retrieval runs on keywords alone, so nothing
+contacts a model. Ask your own question by passing it as an argument.
+
+This is the read path only. Building a graph from your own text needs extraction, which
+needs a model, and that is the full setup below.
+
+## Try it locally
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) and
+[Ollama](https://docs.ollama.com/quickstart), then start Ollama. Setup downloads
+need internet access. Run these commands in bash or zsh:
+
+```bash
+git clone https://github.com/renezander030/graphiti-local.git
+cd graphiti-local
+uv sync --frozen
+ollama pull qwen2.5:7b
+ollama pull nomic-embed-text
+export GRAPHITI_LOCAL_CONFIG="$PWD/config/ollama.example.yaml"
+export KG_WORKSPACE_DIR="$PWD/workspace/local-demo"
+export KG_LADYBUG_PATH="$KG_WORKSPACE_DIR/graph.ladybug"
+uv run --frozen kg-ladybug-setup --database "$KG_LADYBUG_PATH" --apply
+uv run --frozen kg doctor
+uv run --frozen kg-ingest examples/local_memory_demo.jsonl --apply
+uv run --frozen kg ask "Which database does Aurora Analytics use?" example
+```
+
+The synthetic example returns **DuckDB**. Follow the [complete walkthrough](docs/local-quickstart.md)
+to propose PostgreSQL, review and apply that update, and retrieve it from an MCP client.
+Model extraction can be wrong; inspect the returned facts and validity timestamps.
+
+To review extraction before it touches the configured graph, run
+`kg-ingest INPUT --review-output review.jsonl`, inspect the snapshot, then use the
+printed restore command to promote those exact records. Searches return current facts
+by default; `kg ask --history` is the explicit historical view.
+
+## Is it a fit?
+
+Use it for local agent memory with explicit human review. Skip it if you need
+agents to write through MCP or want a hosted service without local setup.
+FalkorDB and Neo4j are also supported.
+
+- [Setup and MCP configuration](docs/local-quickstart.md)
+- [Commands, ingestion, backups, and deployment](docs/reference.md)
+- [Privacy](PRIVACY.md) · [Security](SECURITY.md) · [Container discovery](docs/container.md)
+- [Report a successful or blocked setup](https://github.com/renezander030/graphiti-local/issues/new?template=setup-result.yml)
+
+If this helps your workflow, star the repository and share your setup result.
+
+Maintained by [René Zander](https://renezander.com/projects/graphiti-local/), who builds context layers for AI agents on temporal knowledge graphs.
+
+Independent community project built on [Graphiti](https://github.com/getzep/graphiti),
+not affiliated with or endorsed by Zep. [Apache-2.0](LICENSE).
+
+<!-- mcp-name: io.github.renezander030/graphiti-local -->

graphiti_local-0.4.0/PRIVACY.md

@@ -0,0 +1,16 @@
+# Privacy defaults
+
+- MCP registers six read-only tools. It does not register ingestion, deletion,
+  approval, or graph-maintenance tools.
+- `GRAPHITI_TELEMETRY_ENABLED=false` is set before Graphiti is imported.
+- The default HTTP bind address is `127.0.0.1`.
+- Configuration contains environment-variable references, never credentials.
+- Group names are an allow-list. A caller cannot select an unconfigured graph.
+- Proposals remain in a local JSONL workspace until a human approves them and
+  explicitly runs `kg-workspace drain --apply`.
+- Ladybug extensions are installed only by `kg-ladybug-setup --apply`; opening a
+  graph for reading does not download extensions.
+
+The graph itself may contain sensitive data. Authentication, network exposure,
+database access controls, backups, and retention remain deployment concerns.
+