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

pip install outonote
# or with uv
uv tool install outonote

Usage

# 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

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.