Metadata-Version: 2.5
Name: jezero
Version: 0.1.0
Summary: A shared, searchable library of your agents' past work: connectors, summaries with atoms, SQLite FTS5 search, served over MCP.
Project-URL: Homepage, https://jezero.marsgotta.com
Project-URL: Documentation, https://jezero.marsgotta.com
Project-URL: Source, https://github.com/MarsGotta/jezero
Project-URL: Issues, https://github.com/MarsGotta/jezero/issues
Project-URL: Changelog, https://github.com/MarsGotta/jezero/blob/main/CHANGELOG.md
Author: Marcela Gotta
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,bm25,fts5,knowledge-base,mcp,memory,sqlite
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<3,>=2.0
Requires-Dist: pydantic>=2.12
Requires-Dist: rich>=14.2
Requires-Dist: starlette>=0.27
Requires-Dist: textual>=8.2
Requires-Dist: uvicorn>=0.31.1
Requires-Dist: zstandard>=0.22
Description-Content-Type: text/markdown

# Jezero

**A shared, searchable library of your agents' past work.**

[![ci](https://github.com/MarsGotta/jezero/actions/workflows/ci.yml/badge.svg)](https://github.com/MarsGotta/jezero/actions/workflows/ci.yml)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/MarsGotta/jezero/blob/main/LICENSE)
[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://github.com/MarsGotta/jezero/blob/main/pyproject.toml)
[![MCP](https://img.shields.io/badge/MCP-read--only-6a3ec0.svg)](https://modelcontextprotocol.io)

Your agents forget. Their sessions pile up as gigabytes of transcripts on several
machines, and the decisions in them are written down nowhere else. Jezero collects those
sessions, turns each one into a short summary plus **atoms** (decisions, rationale, fixes,
exact errors, commands that worked, facts, risks), and serves it all, read-only, to every
agent you run over [MCP](https://modelcontextprotocol.io).

<p align="center">
  <img src="https://raw.githubusercontent.com/MarsGotta/jezero/main/docs/architecture.svg" width="100%"
       alt="Sessions from agents on the server and from other computers go through connectors, redaction and a summariser into one SQLite library, which agents query over a read-only MCP server.">
</p>

**[Documentation](https://jezero.marsgotta.com)** ·
[Tutorial](https://github.com/MarsGotta/jezero/blob/main/docs/getting-started/tutorial.md) ·
[Connect an agent](https://github.com/MarsGotta/jezero/blob/main/docs/how-to/connect-agents.md) ·
[Reference](https://github.com/MarsGotta/jezero/blob/main/docs/reference/cli.md) ·
[Changelog](https://github.com/MarsGotta/jezero/blob/main/CHANGELOG.md)

## What it looks like

You ask an agent about something another agent did weeks ago, on another computer. You
do not mention Jezero; the plugin taught it to look:

```text
you    > What did we end up doing with analytics on the shop site?

agent  · search("analytics shop site")
           [412] 2026-09-03  Shop site: remove the analytics script
           [431] 2026-09-10  Shop site: analytics back, only after consent
agent  · later(412, "analytics")
           [431] newer, same subject

agent  > It changed once. On 3 Sep the script was removed [412]; on 10 Sep it came
         back, loaded only after the visitor accepts the consent banner [431].
         That is the current state.
```

Each item is a summary with atoms, the date it happened and its project:

```text
[431] Shop site: analytics back, only after consent        2026-09-10 · shop
summary   The analytics script returns, loaded only after consent. No cookies before.
atoms     decision  Load analytics only after the visitor accepts the banner.
          why       Consent is required before any tracking.
          fix       The banner test ran before the script loaded; wait for the event.
          command   npm run test:consent
```

(Synthetic example. Jezero never ships real transcripts.)

## Features

- **Every agent, every computer.** Connectors for Claude Code, Codex, OpenCode, Hermes
  Agent, Antigravity and Paperclip tasks; plugins upload sessions from other computers.
- **Used by habit.** The plugins teach agents to search Jezero before working, to check
  whether a decision changed later, and to cite what they found, without being asked.
- **Write once, read many.** A small model summarises each session once; searches are
  plain full-text queries that take milliseconds and no GPU.
- **One SQLite file.** No database server to run; a backup is one file
  ([how](https://github.com/MarsGotta/jezero/blob/main/docs/how-to/deploy.md)).
- **Read-only by design.** Agents can search but never write; each key sees only the
  sources it is allowed to.
- **Private by default.** Secrets are redacted before anything is stored, keys are made on
  each computer, and the config never holds a secret.
- **An app for people.** A terminal app to search, watch activity and keep every agent's
  plugin up to date.

**Status: pre-alpha.** Everything above is implemented and tested; email comes next.

## Install

Requires Python 3.12+ on Linux or macOS.

```bash
uv tool install jezero      # or: pipx install jezero, or: pip install jezero
jezero --version
```

To run it as a server from PyPI (config, systemd units, and the plugin bundle downloaded
from the GitHub release with its `SHA256SUMS`), see
[Run Jezero as a service](https://github.com/MarsGotta/jezero/blob/main/docs/how-to/deploy.md#server-from-pypi). Upgrade with
`uv tool upgrade jezero`.

## Get started

From a checkout, with [uv](https://docs.astral.sh/uv/):

```bash
git clone https://github.com/MarsGotta/jezero.git && cd jezero
uv sync
printf '[storage]\npath = "data/jezero.db"\n\n[server]\nhost = "127.0.0.1"\nport = 8765\nrequire_auth = false\n' > jezero.toml
uv run jezero check-config
uv run jezero init
uv run jezero import-jsonl examples/items.example.jsonl --source demo
uv run jezero search "migration rollback"
```

That `jezero.toml` is the tutorial's minimal local library; `jezero.example.toml`
documents every field. The [tutorial](https://github.com/MarsGotta/jezero/blob/main/docs/getting-started/tutorial.md) takes it from
there: serve the library over MCP and connect an agent, in about fifteen minutes.

## Connect your agents

Each computer makes its own key and the server approves it once
([how](https://github.com/MarsGotta/jezero/blob/main/docs/getting-started/connect-a-computer.md)). Then the plugins install straight
from this repository:

```bash
claude plugin marketplace add MarsGotta/jezero && claude plugin install jezero@jezero
codex plugin marketplace add MarsGotta/jezero && codex plugin add jezero@jezero
python3 ~/.jezero-src/jezero-client/jezero_client.py setup --agent codex   # Codex's MCP
hermes plugins install MarsGotta/jezero/plugins/hermes --enable
agy plugin install https://github.com/MarsGotta/jezero/tree/main/plugins/antigravity
```

These follow `main`. To pin a release, add its tag: `MarsGotta/jezero#v0.1.0` for Claude
Code, `MarsGotta/jezero@v0.1.0` for Codex, `tree/v0.1.0/plugins/antigravity` for
Antigravity; Hermes Agent pins only to a commit SHA (`--ref`). The Jezero app installs the
plugins from its own release tag by itself. OpenCode and any other MCP client: see
[Connect an agent](https://github.com/MarsGotta/jezero/blob/main/docs/how-to/connect-agents.md).

## The Jezero app

`jezero` with no command opens a terminal app that searches the library the way an agent
does, shows what each source has been doing, shows the exact context an agent receives,
and installs or updates the plugins on this computer.

<p align="center">
  <img src="https://raw.githubusercontent.com/MarsGotta/jezero/main/docs/app/home.svg" width="100%"
       alt="The Jezero app home: the name in block letters, counters, a 14-day activity chart, projects, sources and the latest items.">
</p>

```bash
uv tool install jezero
jezero ui --demo        # look around with made-up data
```

More in [Use the Jezero app](https://github.com/MarsGotta/jezero/blob/main/docs/how-to/app.md).

## Documentation

Read it at **[jezero.marsgotta.com](https://jezero.marsgotta.com)**, or right here on
GitHub in [`docs/`](https://github.com/MarsGotta/jezero/blob/main/docs/README.md):

| | |
|---|---|
| **Learn** | [Your first library](https://github.com/MarsGotta/jezero/blob/main/docs/getting-started/tutorial.md) · [Connect a second computer](https://github.com/MarsGotta/jezero/blob/main/docs/getting-started/connect-a-computer.md) |
| **Do** | [Run as a service](https://github.com/MarsGotta/jezero/blob/main/docs/how-to/deploy.md) · [Sources](https://github.com/MarsGotta/jezero/blob/main/docs/how-to/sources.md) · [Monitor](https://github.com/MarsGotta/jezero/blob/main/docs/how-to/monitor.md) · [Search quality](https://github.com/MarsGotta/jezero/blob/main/docs/how-to/measure-search.md) · [Agents](https://github.com/MarsGotta/jezero/blob/main/docs/how-to/connect-agents.md) · [Computers and keys](https://github.com/MarsGotta/jezero/blob/main/docs/how-to/devices.md) · [App](https://github.com/MarsGotta/jezero/blob/main/docs/how-to/app.md) · [Troubleshooting](https://github.com/MarsGotta/jezero/blob/main/docs/how-to/troubleshooting.md) |
| **Look up** | [Commands](https://github.com/MarsGotta/jezero/blob/main/docs/reference/cli.md) · [Configuration](https://github.com/MarsGotta/jezero/blob/main/docs/reference/configuration.md) · [Connectors](https://github.com/MarsGotta/jezero/blob/main/docs/reference/connectors.md) · [MCP tools](https://github.com/MarsGotta/jezero/blob/main/docs/reference/mcp-tools.md) · [HTTP API](https://github.com/MarsGotta/jezero/blob/main/docs/reference/http-api.md) · [Client](https://github.com/MarsGotta/jezero/blob/main/docs/reference/client.md) · [Data model](https://github.com/MarsGotta/jezero/blob/main/docs/reference/data-model.md) · [Glossary](https://github.com/MarsGotta/jezero/blob/main/docs/glossary.md) |
| **Understand** | [Architecture](https://github.com/MarsGotta/jezero/blob/main/docs/explanation/architecture.md) · [Search](https://github.com/MarsGotta/jezero/blob/main/docs/explanation/search.md) · [Summaries](https://github.com/MarsGotta/jezero/blob/main/docs/explanation/summaries.md) · [Security](https://github.com/MarsGotta/jezero/blob/main/docs/explanation/security.md) · [Design decisions](https://github.com/MarsGotta/jezero/blob/main/docs/explanation/design-decisions.md) |

## Contributing

Bug reports, ideas and pull requests are welcome: start with
[CONTRIBUTING.md](https://github.com/MarsGotta/jezero/blob/main/CONTRIBUTING.md). To report a vulnerability, see
[SECURITY.md](https://github.com/MarsGotta/jezero/blob/main/SECURITY.md).

## Roadmap

1. Gmail connector (read-only scope, per thread, newsletters skipped).
2. A folder watcher for agents without hooks (Cursor) on other computers.
3. Optional vector search with sqlite-vec.

## The name

Jezero is the Martian crater that once held a lake. Its layered sediments keep the record
of what happened there, and the Perseverance rover sets samples aside in it so they can be
picked up later. That is the whole idea of this project.

## License

[Apache-2.0](https://github.com/MarsGotta/jezero/blob/main/LICENSE)
