Nokori 残り

Nokori

A local-first memory layer that turns corrections into durable agent behavior.

Python >= 3.11 Claude Code native Cursor native Pi supported OMP supported Set and forget

_{remembers corrections · recalls rules in context · blocks risky tools · stores everything locally}

Languages: English | 简体中文 | 繁體中文 | 日本語

Quick Install · How It Works · Architecture · Configuration · CLI Reference · Web UI

What experience leaves behind runs deeper than memory.

Nokori (残り) means what remains: the thing still standing in place after the noise dies down.

Every session ends, and every correction you made evaporates with it. In the next session the agent wakes a stranger again, the same stranger who force-pushes, forgets to run the migration, types a dangerous command straight at the production database.

Nokori refuses to let it forget. It settles every "don't do that" you ever said into recallable behavioral rules: when your words drift back toward that scene, the rule surfaces on its own inside the agent's context. New rules first live as candidates underwater, collecting evidence in the background. Only after the cold path and posthoc evidence trust them can the sharpest ones become Gate-eligible and block the first risky tool call before the agent touches your files.

Your data stays on your machine, in SQLite, the whole way through. Retrieval during a chat never touches a model. Only the post-session extract calls an LLM, and even then it is fed nothing but compressed session fragments. Want it fully offline? Point the endpoint at a local Ollama.

Nokori project one-pager

Who is it for

Repeat mistake hunters
Force pushes, forgotten migrations, commands fired at the wrong database: Nokori remembers the correction after the chat ends.

Cross-repo preference keepers
Teach a behavioral rule once and carry it across projects instead of rebuilding the same instruction stack in every repo.

Local-first operators
Rules sit in SQLite on your own machine, exportable anytime; whole chats are never sent out during retrieval.

Before / After

Without Nokori	With Nokori
The same correction is repeated every session	The correction becomes a durable behavioral rule
Risky tool calls rely on the agent remembering context	Trusted Gate rules can block before the tool runs
Preferences vanish with the chat window	Rules stay local and follow you across projects
Retrieval means waiting on a model	Hot-path recall is deterministic file I/O + scoring

Corrections are distilled into durable local rules
_{Every correction is distilled into a durable local rule.}

One minute overview

You correct Claude Code / Cursor / Pi / OMP
    └─▶ Nokori carves a rule (what scene + what to do)
            └─▶ Next time your words drift near that scene
                    └─▶ The rule auto-writes into the agent's context (reminder)
                            └─▶ If it later becomes trusted + gate_eligible:
                                 block once before the first matching tool call (Gate)

During a chat Nokori only does retrieval and small file I/O, never making you wait on a model. The LLM is only called after the session closes, when it extracts new rules from the transcript at its own pace.

Hot-path local recall without waiting on a model
_{During the chat, recall stays local and deterministic.}

Quick install

A few commands. Local memory. No hosted database.

Prerequisites: Python >= 3.11, Claude Code, Cursor, Pi, or OMP already installed

# Recommended: uv with local semantic retrieval
uv tool install "nokori[local-embed]"

# Register hooks / extension bridge
nokori install --pi         # Pi only  -> ~/.pi/agent/extensions/nokori.ts
nokori install --omp        # OMP only -> ~/.omp/agent/extensions/nokori.ts
# Use --all for Claude Code + Cursor, --cursor for Cursor, default for Claude Code only

# Verify (Pi/OMP installs are reported as hooks.pi / hooks.omp)
nokori health

On Pi and OMP, recall is injected on before_agent_start, Gate checks run on tool_call, and post-session extraction starts on session_shutdown using the current session file. Pi reloads are ignored so /reload never closes the active session in Nokori.

Other install methods

# Minimal install (BM25 only, no local model)
uv tool install nokori

# pipx alternative
brew install pipx && pipx ensurepath
pipx install "nokori[local-embed]"

# Dedicated venv
python3 -m venv ~/.local/venvs/nokori
~/.local/venvs/nokori/bin/pip install "nokori[local-embed]"
echo 'export PATH="$HOME/.local/venvs/nokori/bin:$PATH"' >> ~/.zshrc

# From source
git clone https://github.com/KorenKrita/nokori.git && cd nokori
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[local-embed,dev]"

Full installation guide (Claude Code / Cursor / Pi / OMP config, updating, uninstalling) in Installation

Quick start

# 1. Add a candidate rule
nokori add \
  --trigger "Force pushing to a shared branch" \
  --action "Use --force-with-lease, or push to a new branch" \
  --severity high_risk

# 2. Verify the shadow match
nokori test "I'll just git push --force this branch"

# 3. Run maintenance (let evidence move rules forward)
nokori maintain

# 4. Rule out of date? Dismiss it
nokori dismiss <short_id>

Just open Claude Code, Cursor, Pi, or OMP and work as usual. When a rule matches, the agent sees the injected reminder before it replies. For trusted + gate_eligible rules, the first sensitive tool call is blocked once.

Gate blocks a risky tool call before files are touched
_{Trusted rules can stop the first risky tool call before it reaches your files.}

Core features

Autonomous quality flywheel candidate → active → trusted; rules must earn evidence before gaining authority.	Zero model calls on the hot path Hooks do deterministic retrieval, matching, and scoring only; no LLM wait between prompt and reply.
Hybrid retrieval BM25 out of the box, optional local or remote semantic vectors, and RRF fusion when both are available.	Conservative Gate Only trusted + gate_eligible rules can block tools, and only once per turn.
Shadow evidence Candidates accumulate counterfactual evidence in the background without disturbing the current chat.	Local-first storage SQLite + filesystem, data never leaves your machine during recall, and offline LLMs are optional.
Cross-tool support Native Claude Code and Cursor hooks, plus Pi and OMP through small TypeScript bridges that reuse the same Python dispatcher.	Web UI Run `nokori web` for a visual dashboard to inspect rules, logs, lifecycle state, and configuration.

Documentation

Guide	What it gives you
🚀 Installation	uv / pipx install, Claude Code / Cursor / Pi / OMP config, updates, uninstalling
🧠 Architecture	flywheel mechanism, hook timing, injection vs Gate, Shadow Pool
⚙️ Configuration	`config.toml`, environment variables, full reference
🔎 Retrieval Engine	BM25, embeddings, RRF fusion, injection tiers
🌱 Rule Lifecycle	state machine, promotion evidence, maintenance tasks
🧊 Automatic Extraction	cold-path pipeline, merge strategy, async mode
🛡️ Gate Mechanism	two-layer matching, configuration, prompt-hash safety
⌨️ CLI Reference	all commands and options
🖥️ Web UI	visual dashboard features and development

Relationship with existing systems

System	Relationship
CLAUDE.md	Complementary. Nokori doesn't touch your CLAUDE.md; it handles the dynamic "when X, do Y"
Claude Code auto-memory	No conflict. Memory leans factual, Nokori leans behavioral rules
Other memory plugins	Hooks can coexist, but avoid stacking many context-injection plugins

Data storage

All data lives in one local directory, ~/.nokori/. There is no network sync. Rules store behavioral descriptions, not your source code. Only the cold-path extract calls an LLM; point the endpoint at a local Ollama for fully offline operation.

Development

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[local-embed,dev]"
python -m pytest tests/

Project constraints: hot-path hooks use only stdlib + urllib (no LLM calls between prompt and reply), all hooks wrapped in top-level try/except fail-open. Base install includes fastapi + uvicorn for the web dashboard.

License

MIT

Metadata

Release files for nokori 0.5.54

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nokori 0.5.54
File	Size	Uploaded
nokori-0.5.54.tar.gz	1.5 MB	Jul 10, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for nokori 0.5.54
File	Interpreter	ABI	Platform	Reset
nokori-0.5.54-py3-none-any.whl 1.4 MB Jul 10, 2026	Python 3	none	any	Details

Total release size: 2.8 MB

Release files / nokori-0.5.54.tar.gz

Download URL	nokori-0.5.54.tar.gz
Size	1.5 MB
Tags	Source
SHA-256 checksum How to use checksums	`faa0746c3fd41f88f18085a7cee7b278636e42a38449922af7d33ba389fd44f7`
BLAKE2b-256 checksum How to use checksums	`408806d390380c6887d07bbf2fdf3519ee3dfa484677839fd5d7c1f51cdb261b`
Upload date	Jul 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Release files / nokori-0.5.54-py3-none-any.whl

Download URL	nokori-0.5.54-py3-none-any.whl
Size	1.4 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`2f55cc9f22ec99dde9778e5b0dc39d298026dd27b2127c3b1268f13d29619f2f`
BLAKE2b-256 checksum How to use checksums	`e00c35226f9bf5c76d7d91f4f6854c397fecb9f9d09679768b72f4607387da9d`
Upload date	Jul 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.12`