Metadata-Version: 2.4
Name: aizk
Version: 0.0.1
Summary: A self-hosted multi-tenant memory engine that turns a Zettelkasten into scoped agent-queryable memory over MCP
Project-URL: Homepage, https://phvv.me/aizk
Project-URL: Documentation, https://phvv.me/aizk
Project-URL: Repository, https://github.com/phvv-me/aizk
Project-URL: Issues, https://github.com/phvv-me/aizk/issues
Author-email: Pedro Valois <contact@phvv.me>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: aizk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.14
Requires-Dist: alembic<2,>=1.14
Requires-Dist: asyncpg<0.31,>=0.30
Requires-Dist: chonkie[code]<2,>=1.6
Requires-Dist: cyclopts<5,>=4
Requires-Dist: dateparser<2,>=1.2
Requires-Dist: fastmcp<3,>=2.11
Requires-Dist: gliner2>=0.1
Requires-Dist: httpx<0.29,>=0.28
Requires-Dist: identify<3,>=2.6
Requires-Dist: inflection<0.6,>=0.5
Requires-Dist: jinja2<4,>=3.1
Requires-Dist: jsonlines<5,>=4.0
Requires-Dist: loguru<0.8,>=0.7.3
Requires-Dist: mainboard>=0.0.8
Requires-Dist: networkx<4,>=3.4
Requires-Dist: numpy<3,>=2
Requires-Dist: openai<2,>=1.109
Requires-Dist: patos
Requires-Dist: pgqueuer<1,>=0.10
Requires-Dist: pgvector<0.5,>=0.3.6
Requires-Dist: pydantic-settings<3,>=2.5
Requires-Dist: python-slugify<9,>=8.0
Requires-Dist: rlsalchemy
Requires-Dist: scipy<2,>=1.14
Requires-Dist: sqlalchemy[asyncio]<3,>=2.1.0b3
Requires-Dist: sqlmodel<0.1,>=0.0.39
Requires-Dist: tenacity<10,>=9
Provides-Extra: dev
Requires-Dist: dirty-equals>=0.8; extra == 'dev'
Requires-Dist: faker>=30; extra == 'dev'
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: mainboard; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: polyfactory<3,>=2.22; extra == 'dev'
Requires-Dist: pyrefly>=1; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest-mock>=3.14; extra == 'dev'
Requires-Dist: pytest-subprocess>=1.5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ranx<0.4,>=0.3.20; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: syrupy>=4; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs-static-i18n>=1.2; extra == 'docs'
Description-Content-Type: text/markdown

<div align="center">

<!-- [![aizk banner](https://raw.githubusercontent.com/phvv-me/aizk/main/docs/assets/banner.png)](https://phvv.me/aizk) -->

[![CI](https://github.com/phvv-me/aizk/actions/workflows/ci.yml/badge.svg)](https://github.com/phvv-me/aizk/actions/workflows/ci.yml)
[![Publish](https://github.com/phvv-me/aizk/actions/workflows/publish.yml/badge.svg)](https://github.com/phvv-me/aizk/actions/workflows/publish.yml)
[![PyPI](https://img.shields.io/pypi/v/aizk)](https://pypi.org/project/aizk/)
[![Python](https://img.shields.io/pypi/pyversions/aizk)](https://pypi.org/project/aizk/)
[![Docs](https://img.shields.io/badge/docs-phvv.me%2Faizk-EAB308)](https://phvv.me/aizk)
[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/phvv-me/aizk/actions/workflows/ci.yml)

</div>

[🇧🇷](https://phvv.me/aizk/pt-BR/) [🇲🇽](https://phvv.me/aizk/es/) [🇯🇵](https://phvv.me/aizk/ja/) [🇨🇳](https://phvv.me/aizk/zh/)

A self-hosted multi-tenant memory engine that turns a Zettelkasten into scoped agent-queryable memory over MCP

## What this is

aizk is a memory an AI assistant can actually keep. Text goes in, an entity and fact knowledge
graph comes out, addressed by meaning so the same knowledge extracted twice never duplicates.
Everything lives in one self-hosted Postgres, and row level security enforces who can see what
at the database layer, private notes, shared projects, and overlapping groups never cross. It
speaks MCP, so Claude or any other MCP-capable assistant calls it directly. Full explanation at
[phvv.me/aizk](https://phvv.me/aizk).

## Quickstart

One command brings up the whole engine, Postgres, the embed, rerank, and extraction containers,
and one aizk container that is the MCP server, the background worker, and the scheduled auto-backup
at once. It migrates and comes up ready over HTTP with nothing else to run.

```sh
docker compose up -d
```

Then call its tools from any MCP client.

```python
from fastmcp import Client

async with Client("http://localhost:8080/mcp") as client:
    await client.call_tool("remember", {"text": "aizk runs entirely on local hardware."})
    result = await client.call_tool("recall", {"query": "where does aizk run?"})
    print(result.data)
```

Every docker-compose knob and every `Settings` default live in one file, `.env.example`, copy
it to `.env` and edit, both compose and the app read the same `AIZK_`-prefixed variables. Running
the server, worker, or backup outside the container is a plain `pip install aizk` and the matching
`aizk` command. See [Operations](https://phvv.me/aizk/operations/) for deployment and backups.

## The flows

```mermaid
flowchart LR
    A[agent] -->|remember, ingest| W[write path<br/>chunk, extract, consolidate]
    A -->|recall, get_context| Re[read path<br/>fused retrieval]
    W --> P[(Postgres<br/>knowledge graph + row level security)]
    Re --> P
    P --> Re --> A
```

Writing turns text into a typed entity and fact graph, one content row shared by meaning plus
one scoped, bi-temporal claim per owner. Reading fuses five retrieval lanes behind one Postgres
round trip, filtered to exactly what the caller's own scopes make visible before a row is ever
considered. The full breakdown of both, with a diagram for each stage, lives in
[Engine](https://phvv.me/aizk/engine/).
