llm-note

English · Deutsch · Español · 简体中文 · 日本語 · Русский

Note

Local-first note storage: llm-note stores notes in local SQLite and plain-text files. Core note storage does not require a hosted notes service or API key. The optional web interface binds to loopback; host settings govern network access.

Quick Navigation

Overview & Why This Exists
Key Capabilities & Architecture
Visual System Architecture
Note & Transfer Lifecycle Sequence
Target Personas & Discoverability
Comparative Matrix vs. Alternatives
Governance & Implementation Notes
Denkarium Local Web GUI Guide
CLI Complete Reference & Examples
Python API Guide & Code Examples
Agent Skill & Workflow Integration
File-Based Inboxes & Transfer Semantics
Sibling Ecosystem Matrix
Third-Party Dependencies & License Scope
Security Policy & Response Targets
Verification & Contract Test Suite
Legal Note: § 521 BGB
Roadmap & Changelog

1. Overview & Why This Exists

llm-note is an ultra-lightweight, zero-service local notebook engine — primarily a notebook for humans that AI assistants and coding agents write into for their user, and, depending on how it's used, a notebook shared by both.

AI assistants and LLM agents frequently need a place to record decisions, capture context observations, and brainstorm ideas so their user can read them later — and, in shared use, so human and agent can both refer back to them. Traditional solutions require heavy vector databases, hosted SaaS subscriptions, or bloated Electron applications that consume system resources and leak telemetry.

Modes

llm-note doesn't enforce a mode — it's the same plain notebook used in whichever of these ways fits the moment:

For humans, from LLMs (default): the human reads; their AI assistant writes notes for them.
From humans, for LLMs: the human leaves notes for their assistant to read.
Shared cowork space: human and AI assistants write into the same notebook — your LLMs share your space.

llm-note provides the ideal architectural middle ground:

Zero External Runtime Dependencies: Built entirely upon the Python standard library (sqlite3, http.server, urllib, argparse, json, pathlib).
Dual-Store Flexibility: Combines structured SQLite thought entries (CLI default: llm-note.db; path configurable) with human-editable plain-text inboxes (notebooks/*.txt).
BACH Extraction Provenance: Cleanly decoupled from the BACH desktop assistant codebase, specifically Notizblock and Denkarium, and open-sourced under the permissive MIT license.

2. Key Capabilities & Architecture

SQLite Thought Log (NoteStore): Store structured notes, logbook entries, categories, mood values, and task promotion markers with full ACID reliability.
Plain-Text Notebook Inboxes (FileNotebookStore): Manage portable plain-text notes with #NB: categorization markers and atomic cross-process file locking.
Embedded Denkarium Web UI: Zero-install loopback browser interface bound strictly to 127.0.0.1 using standard library http.server and system fonts.
Multi-Locale Translation: Native message localization across 6 languages: English, German, Spanish, Simplified Chinese, Japanese, and Russian.
Agent Skill Source: The source repository contains skills/llm-note/SKILL.md; pyproject.toml packages only llm_note, so the wheel does not include that source path.
Deterministic Search: Literal substring searches without wildcard surprises, with strict query limits (0 to 1000).

3. Visual System Architecture

graph TD
    subgraph Clients["Clients & Interfaces"]
        CLI["llm-note CLI (argparse)"]
        GUI["Denkarium Web GUI (127.0.0.1)"]
        PyAPI["Python API (llm_note)"]
        Skill["Agent Skill (SKILL.md)"]
    end

    subgraph CoreEngine["llm-note Core Engine"]
        NoteStore["NoteStore (SQLite Engine)"]
        FileStore["FileNotebookStore (Plain-Text Engine)"]
        HTTP["http.server (Loopback Only)"]
        I18N["Locales (EN, DE, ES, ZH, JA, RU)"]
    end

    subgraph LocalStorage["Local Storage Layer"]
        DB[("llm-note.db<br/>(SQLite Thought Log; CLI default)")]
        Notebooks["notebooks/*.txt<br/>(Plain-Text Inboxes)"]
        LockFile[".llm-note.lock (Atomic Coordination)"]
    end

    CLI -->|"Direct command"| NoteStore
    CLI -->|"File operations"| FileStore
    GUI -->|"HTTP requests"| HTTP
    HTTP -->|"Internal calls"| NoteStore
    PyAPI -->|"In-process API"| NoteStore
    PyAPI -->|"In-process API"| FileStore
    Skill -->|"Tool call"| CLI
    Skill -->|"Direct import"| PyAPI

    NoteStore -->|"ACID queries"| DB
    NoteStore -->|"Localized strings"| I18N
    FileStore -->|"Atomic file writes"| Notebooks
    FileStore -->|"Cross-process lock"| LockFile

4. Note & Transfer Lifecycle Sequence

sequenceDiagram
    autonumber
    actor UserOrAgent as "Agent / Developer"
    participant CLI as "CLI / Python API"
    participant FileStore as "FileNotebookStore"
    participant NoteStore as "NoteStore (SQLite)"
    participant Denkarium as "Denkarium GUI (127.0.0.1)"

    UserOrAgent ->> NoteStore: write("Architecture decision", category="design")
    NoteStore ->> NoteStore: Insert thought record with timestamp & mood
    NoteStore -->> UserOrAgent: Return Entry(id=1, category="design")

    UserOrAgent ->> FileStore: write("Inbox item - #NB: Project Ideas")
    FileStore ->> FileStore: Acquire .llm-note.lock & append to inbox.txt
    FileStore -->> UserOrAgent: Note saved to plain-text inbox

    UserOrAgent ->> FileStore: transfer_marked_entries()
    FileStore ->> FileStore: Parse #NB: target notebook & assign stable #LLM-NOTE-ID
    FileStore ->> FileStore: Atomically move entry to target notebook & release lock
    FileStore -->> UserOrAgent: Transfer complete (0 duplicate risk)

    UserOrAgent ->> Denkarium: Open loopback GUI (http://127.0.0.1:8000/)
    Denkarium ->> NoteStore: GET /api/notes (query SQLite thoughts)
    NoteStore -->> Denkarium: JSON response with filtered thought stream
    Denkarium -->> UserOrAgent: Interactive visual view rendered via system fonts

5. Target Personas & Discoverability

llm-note is tailored for four specific personas and workflows:

Persona ID	Target Persona	Core Need	Key Value Provided
`[PERSONA-01]`	Autonomous Agent Builders	Lightweight thought memory across LLM context resets	Zero-dependency SQLite store with instant embeddability
`[PERSONA-02]`	Privacy-Conscious Developers	Local SQLite notes and text inboxes without a hosted notes service	Local-first storage; host policy controls network access
`[PERSONA-03]`	Desktop AI Assistant Users	Instant visual thought browser without Node/Electron	Built-in loopback Denkarium GUI (`127.0.0.1`)
`[PERSONA-04]`	Open-Science Researchers	Git-trackable, auditable thought and experiment logs	Plain-text inboxes and standard SQLite single-file databases

High-Intent Search Queries

English: local-first LLM notes, SQLite note store for agents, agent notebook CLI, private AI notebook, zero-dependency agent memory python, Denkarium agent thought browser.
German: lokaler KI Agenten Notizspeicher, autonomes Agenten Gedächtnis ohne Cloud, datenschutzkonformer Notizblock offline, Agenten Denkarium Browser UI.

6. Comparative Matrix vs. Alternatives

Architectural Dimension	`llm-note`	Obsidian	Joplin	Vector Databases	Raw SQLite CLI
1. Storage Engine	SQLite + TXT	Markdown files	SQLite / Sync	Vector embeddings	Single SQLite file
2. Runtime Dependencies	0 (Stdlib only)	Electron / Node	Electron / DB	Heavy C++ / Py	0 (C binary)
3. Network requirements	Local storage; host policy applies	Not assessed	Not assessed	Not assessed	Not assessed
4. Agent Python API	First-Class Native	Community REST	Community API	Complex client	Raw SQL required
5. Embedded Web GUI	Built-in (127.0.0.1)	Desktop App	Desktop App	Separate SaaS	None
6. Plain-Text Inbox Sync	Built-in (`#NB:`)	Manual folders	Manual imports	N/A	Manual scripts
7. Multi-Locale Engine	6 Bundled Locales	Community pack	Community pack	English-centric	English only
8. Process permissions	Inherits caller permissions	Not assessed	Not assessed	Not assessed	Not assessed
9. Agent Skill Source	Source repository; not in wheel	Third-party	Third-party	Custom code	None
10. Security response information	Maintainer targets in SECURITY.md	Not assessed	Not assessed	Not assessed	Not assessed

7. Governance & Implementation Notes

The items below describe current implementation characteristics based on source. They are not immutable guarantees or an external security certification:

INV-LOCAL-01: Local-first storage — Notes are stored in local SQLite and plain-text files; this does not block network access at the host level.
INV-LOCAL-02: SQLite Single-File Storage — Structured ACID database; the CLI default file is llm-note.db and the path is configurable.
INV-LOCAL-03: Plain-Text Notebook Inboxes — Human-readable text inboxes (notebooks/*.txt) with #NB: categorization.
INV-LOCAL-04: Standard Library Only — Zero third-party runtime dependencies; runs on any standard Python 3.10+ runtime.
INV-LOCAL-05: Crash-Safe Atomic Transfers — Cross-process locking via .llm-note.lock and #LLM-NOTE-ID idempotency markers.
INV-LOCAL-06: Loopback-Bound Web GUI — Denkarium strictly listens on 127.0.0.1; supports --no-browser.
INV-LOCAL-07: Multi-Locale I18N — 6 bundled localization catalogs: EN, DE, ES, ZH, JA, RU.
INV-LOCAL-08: Process permissions — The application does not request elevation and inherits the permissions of the process that launches it.
INV-LOCAL-09: Agent skill source — The source repository contains skills/llm-note/SKILL.md; pyproject.toml packages only llm_note, so the wheel does not include that source path.
INV-LOCAL-10: Maintainer response targets — See SECURITY.md; acknowledgement and triage targets are not an SLA or a fix deadline.

8. Denkarium Local Web GUI Guide

The Denkarium GUI provides an instant, zero-install visual thought dashboard. Choose one of the six languages from the Language menu. The choice is per browser and is saved in that browser’s local storage. When starting the GUI with an explicit --locale, that value takes priority for the initial language; otherwise, it uses the saved browser choice and falls back to English.

# Launch Denkarium with default settings (opens http://127.0.0.1:8000/)
llm-note gui

# Specify custom port, database, and German locale
llm-note --db data/notes.db --locale de gui --port 8765

# Headless mode for background servers or automated testing
llm-note gui --port 8765 --no-browser

GUI Architectural Highlights

Zero Framework Bloat: Pure vanilla HTML/CSS/JavaScript served directly via Python's standard http.server.
Responsive Layout: Designed for both desktop and mobile viewports with system-native fonts (Segoe UI, SF Pro, system-ui).
REST JSON Endpoints:
- GET /api/notes?search=<query>&category=<cat>&limit=<n>
- POST /api/notes (creates a new thought entry)

9. CLI Complete Reference & Examples

Installation

llm-note is not published on PyPI yet. Install it from the repository (Python 3.10+, no third-party runtime dependencies):

pip install git+https://github.com/doc-bricks/llm-note.git
# or from a local clone
git clone https://github.com/doc-bricks/llm-note.git && cd llm-note && pip install .

This provides the llm-note command and the llm_note Python package.

# Write a note with category and mood
llm-note write "Refactor caching layer" --cat dev --mood 4

# Read recent notes (default limit 10)
llm-note read --limit 5

# Search notes literally (no SQL wildcard expansion)
llm-note search "caching"

# Brainstorm ideas for future promotion
llm-note brainstorm "Zero-copy serialization options"

# View summary statistics
llm-note stats

# Run with custom database and German locale
llm-note --db custom/notes.db --locale de read --limit 3

10. Python API Guide & Code Examples

from llm_note import NoteStore, FileNotebookStore

# 1. Initialize SQLite NoteStore
notes = NoteStore("data/notes.db")

# 2. Write a structured thought entry
entry = notes.write(
    content="Implement deterministic seed for test suite",
    category="testing",
    mood=4
)
print(f"Created entry #{entry.id} at {entry.created_at}")

# 3. Search notes
matches = notes.search("deterministic")
for match in matches:
    print(f"Found: {match.content} [{match.category}]")

# 4. Promote a thought to a task
notes.promote(entry.id, target="task")

# 5. Coordinate plain-text notebooks
notebooks = FileNotebookStore("notebooks")
notebooks.write("Draft release announcement\n#NB: Marketing")
transferred = notebooks.transfer_marked_entries()
print(f"Transferred {transferred} entries to topic notebooks.")

11. Agent Skill & Workflow Integration

The source repository contains an agent skill definition at skills/llm-note/SKILL.md. The wheel packages only llm_note as declared in pyproject.toml, so the source-only skill path is not claimed as wheel content. Autonomous agents (such as Claude Code, Antigravity, or Codex) can invoke llm-note to record observations and maintain scratchpads.

# Agent Tool Invocation Example
To save an interim research observation:
`llm-note write "Identified 3 edge cases in token parsing" --cat research`

12. File-Based Inboxes & Transfer Semantics

Inbox Default: Entries without markers are written to notebooks/inbox.txt.
Topic Targeting: Append #NB: <Topic Name> to route an entry to notebooks/<Topic Name>.txt.
Atomic Transfer: Calling transfer_marked_entries() extracts all marked entries, assigns an idempotent #LLM-NOTE-ID: <hash> marker, appends them to the target topic file, and rewrites the source file atomically.
Concurrency Safety: Multi-process contention is prevented by an advisory .llm-note.lock file in the notebook directory.

13. Sibling Ecosystem Matrix

The entries below link to related projects. The FolderHome row also describes a provider relationship scoped to its cited source commit and pin; it does not assert compatibility with current main or live enablement.

Project	Focus & Role in Ecosystem	Link
ellmos-ai/FolderHome	Its component manifest pins this repository at `b5fe59fc155ded9603566aa0fb920a53181a2426` and declares `notes.read` plus gated `notes.write` (`default_mode = dry-run`, `live_enabled = false`).	manifest at 51d5dc7, provider guide
doc-bricks/llm-note	Local-first thought and notebook core for agents	doc-bricks/llm-note
doc-bricks/MediaBrain	Personal video and music library with smart playlists and streaming history	doc-bricks/MediaBrain
doc-bricks/MailProcessor	Windows tray app for launching the local Universal Mail tools	doc-bricks/MailProcessor
file-bricks/ProSync	Robust, cross-platform directory synchronization	file-bricks/ProSync
file-bricks/CloudLockFixer	Delays file operations in cloud-sync folders and verifies copy/delete fallbacks with SHA-256	file-bricks/CloudLockFixer
open-bricks organization profile	GitHub organization profile and umbrella catalog; not a specific repository	open-bricks on GitHub

14. Third-Party Dependencies & License Scope

llm-note declares no additional Python runtime package dependencies in pyproject.toml. Its core uses the Python standard library and SQLite supplied by the Python environment.

Scoped notes on direct declared dependencies: THIRD_PARTY_LICENSES.md and THIRD_PARTY_LICENSES.txt. They are not complete SBOMs.
The dependency notes do not certify the license status of complete transitive build or development dependency trees.
The process does not request administrative elevation and inherits the launching process permissions; this is not a platform certification.

15. Security Policy & Response Targets

The reporting route and maintainer response targets are documented in SECURITY.md:

Implementation boundary: Core notes use local storage and the optional web interface binds to loopback. The application does not block host network access or sandbox the process.
Maintainer response targets: Acknowledgement within 48 hours and initial triage within 5 business days are targets, not an SLA or a promised fix deadline.
Contact: Submit confidential reports through the private reporting method described in SECURITY.md.

16. Verification & Contract Test Suite

Run the full verification suite locally:

# Execute unit and contract tests
python -m pytest -ra -v

# Run fast Ruff linter
ruff check .

# Verify bytecode compilation
python -m compileall -q .

17. Legal Note: § 521 BGB

Dieser Hinweis trifft keine Aussage dazu, ob § 521 BGB auf eine konkrete Bereitstellung anwendbar ist oder welche Haftungsfolgen eintreten. Das hängt von den Umständen des Einzelfalls ab.

Section 521 of the German Civil Code may be relevant depending on the specific facts. This note does not determine whether it applies to a particular distribution or what liability consequences follow.

18. Roadmap & Changelog

Changelog: See detailed version history in CHANGELOG.md.
Roadmap & Tasks: Review current milestones and open backlog items in TODO.md.
AI Context Index: Complete LLM discovery index available in llms.txt.

Name		Name	Last commit message	Last commit date
.github		.github
assets		assets
docs		docs
llm_note		llm_note
plugin		plugin
references		references
skills/llm-note		skills/llm-note
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MARKETING-LOG.txt		MARKETING-LOG.txt
PROVENANCE.md		PROVENANCE.md
README.md		README.md
README_de.md		README_de.md
README_es.md		README_es.md
README_ja.md		README_ja.md
README_ru.md		README_ru.md
README_zh-Hans.md		README_zh-Hans.md
RELEASE_GATE.md		RELEASE_GATE.md
SECURITY.md		SECURITY.md
THIRD_PARTY_LICENSES.md		THIRD_PARTY_LICENSES.md
THIRD_PARTY_LICENSES.txt		THIRD_PARTY_LICENSES.txt
TODO.md		TODO.md
ellmos-module.v2.json		ellmos-module.v2.json
llms.txt		llms.txt
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
requirements.txt		requirements.txt

Navigation Menu

Repository navigation

About

Repository files navigation

llm-note

Quick Navigation

1. Overview & Why This Exists

Modes

2. Key Capabilities & Architecture

3. Visual System Architecture

4. Note & Transfer Lifecycle Sequence

5. Target Personas & Discoverability

High-Intent Search Queries

6. Comparative Matrix vs. Alternatives

7. Governance & Implementation Notes

8. Denkarium Local Web GUI Guide

GUI Architectural Highlights

9. CLI Complete Reference & Examples

Installation

10. Python API Guide & Code Examples

11. Agent Skill & Workflow Integration

12. File-Based Inboxes & Transfer Semantics

13. Sibling Ecosystem Matrix

14. Third-Party Dependencies & License Scope

15. Security Policy & Response Targets

16. Verification & Contract Test Suite

17. Legal Note: § 521 BGB

18. Roadmap & Changelog

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

llm-note

Quick Navigation

1. Overview & Why This Exists

Modes

2. Key Capabilities & Architecture

3. Visual System Architecture

4. Note & Transfer Lifecycle Sequence

5. Target Personas & Discoverability

High-Intent Search Queries

6. Comparative Matrix vs. Alternatives

7. Governance & Implementation Notes

8. Denkarium Local Web GUI Guide

GUI Architectural Highlights

9. CLI Complete Reference & Examples

Installation

10. Python API Guide & Code Examples

11. Agent Skill & Workflow Integration

12. File-Based Inboxes & Transfer Semantics

13. Sibling Ecosystem Matrix

14. Third-Party Dependencies & License Scope

15. Security Policy & Response Targets

16. Verification & Contract Test Suite

17. Legal Note: § 521 BGB

18. Roadmap & Changelog

License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages