Metadata-Version: 2.5
Name: outonote
Version: 0.1.0
Summary: Plain-markdown memory system for AI agents: BM25 search and community voting over folders of immutable .md documents. No embeddings, no database.
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai-agent,bm25,markdown,memory,notes,search
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="logo.svg" alt="outonote logo" width="800">
</p>

# outonote

A plain-markdown memory system for AI agents.

- Documents are plain `.md` files in a folder (a **document space**). No wiki-style classification, no embeddings, no database.
- Search uses BM25 over unigram + bigram tokens, ranked together with community votes and document recency.
- Any agent can `upvote` / `downvote` a document; votes are stored as human-readable JSON inside the document space.
- Only top-level `.md` files are searchable documents. Files in subfolders are *reference documents / reference files* and are excluded from search.
- Documents are immutable once created. To correct a document, write a new one — and leave the old document's evaluation to the readers who come after you.

## Install

```bash
pip install outonote
# or with uv
uv tool install outonote
```

## Usage

```bash
# Search a document space
outonote search ~/doc/doc1 "how to configure ranking weights"

# Upvote / downvote a document
outonote upvote ~/doc/doc1/ranking.md
outonote downvote ~/doc/doc1/outdated-guide.md
```

Search results show: title, file path, vote count, and creation time.

Each document space (folder) is fully independent: separate index cache and separate
vote file. `~/doc/1/name.md` and `~/doc/2/name.md` never interfere with each other.

## Development

```bash
uv sync --extra dev  # set up the environment
uv run pytest        # run the test suite
```

`test-docs/` is a sandbox document space for experimenting with search and
votes; `docs/` holds the project documentation.
