memir 0.3.0__tar.gz

memir-0.3.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to Memir are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and Memir follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] — 2026-06-08
+
+First public release.
+
+### Added
+- **First-class failure memory.** `record_failure(attempt, reason, lesson)` and a
+  `check_failure(...)` guard the agent can consult *before* acting.
+- **Three memory kinds:** facts, decisions (with reasons), and failures, in a tiny
+  local SQLite store.
+- **0-token, deterministic writes.** No LLM in the capture path.
+- **Local semantic recall by default** via `model2vec` `potion-retrieval-32M`
+  (numpy-only, ~1 ms, CPU, offline) with graceful keyword fallback.
+- **Token-budgeted `briefing(budget_tokens=...)`** that prioritises failures over
+  decisions over facts.
+- **`recall()` with multi-hop (`hops`) and a hybrid embedding + FTS5 RRF ranker.**
+- **Safe `consolidate()`** that merges only genuine restatements, never distinct
+  facts.
+- **`capture_error()` / `watch()`** auto-capture that stores only non-obvious
+  failures (textbook errors are skipped to avoid bloat).
+- **CLI** (`memir setup|start|doctor|remember|decision|failure|recall|check|briefing|stats`).
+- **MCP server** (`memir start`) exposing the tools over stdio JSON-RPC.
+- **Optional local CPU extras:** `memir[rerank]` (cross-encoder reranker),
+  `memir[nli]` (NLI reasoner), `memir[contextual]` (BGE encoder), `memir[ml]`.
+
+### License
+- Released under **PolyForm Noncommercial 1.0.0** (free for noncommercial use).
+
+[0.3.0]: https://github.com/jabir-al-nahian/memir/releases/tag/v0.3.0

memir-0.3.0/CITATION.cff

@@ -0,0 +1,25 @@
+cff-version: 1.2.0
+message: "If you use Memir in your research, please cite it as below."
+title: "Memir: a local-first, zero-token memory layer with first-class failure memory for coding agents"
+abstract: >-
+  Memir is a local-first long-term memory layer for coding agents. It stores
+  facts, decisions, and a first-class failure memory in a tiny SQLite store with
+  deterministic, zero-token writes, and serves a token-budgeted briefing plus a
+  failure guard. Semantic recall runs on a local CPU static-embedding model
+  (model2vec), requiring no API keys or GPU.
+type: software
+authors:
+  - family-names: Nahian
+    given-names: ""
+version: "0.3.0"
+date-released: "2026-06-08"
+license: "PolyForm-Noncommercial-1.0.0"
+repository-code: "https://github.com/jabir-al-nahian/memir"
+url: "https://github.com/jabir-al-nahian/memir"
+keywords:
+  - coding agents
+  - long-term memory
+  - failure memory
+  - retrieval-augmented generation
+  - local-first
+  - model context protocol

memir-0.3.0/LICENSE.md

@@ -0,0 +1,116 @@
+Required Notice: Copyright (c) 2026 Nahian (https://github.com/jabir-al-nahian/memir)
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both
+strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything
+you might do with the software that would otherwise infringe the licensor's
+copyright in it for any permitted purpose. However, you may only distribute the
+software according to [Distribution License](#distribution-license) and make
+changes or new works based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of
+the software. Your license to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms or the URL for them above, as well as copies of
+any plain-text lines beginning with `Required Notice:` that the licensor
+provided with the software. For example:
+
+> Required Notice: Copyright (c) 2026 Nahian (https://github.com/jabir-al-nahian/memir)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new
+works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent
+claims the licensor can license, or becomes able to license, that you would
+infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public
+knowledge, personal study, private entertainment, hobby projects, amateur
+pursuits, or religious observance, without any anticipated commercial
+application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research
+organization, public safety or health organization, environmental protection
+organization, or government institution is use for a permitted purpose regardless
+of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not
+limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to
+anyone else, or prevent the licensor from granting licenses to anyone else. These
+terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to
+infringement of any patent, your patent license for the software granted under
+these terms ends immediately. If your company makes such a claim, your patent
+license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these
+terms, or done anything with the software not covered by your licenses, your
+licenses can nonetheless continue if you come into full compliance with these
+terms, and take practical steps to correct past violations, within 32 days of
+receiving notice. Otherwise, all your licenses end immediately.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising out
+of these terms or the use or nature of the software, under any kind of legal
+claim.*
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the
+**software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over, are
+under the control of, or are under common control with that organization.
+**Control** means ownership of substantially all the assets of an entity, or the
+power to direct its management and policies by vote, contract, or otherwise.
+Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these
+terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

memir-0.3.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include LICENSE.md
+include README.md
+include CHANGELOG.md
+include CITATION.cff
+include memir/py.typed
+recursive-include examples *.py *.json
+recursive-include docs *.md
+prune tests

memir-0.3.0/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: memir
+Version: 0.3.0
+Summary: Local memory for coding agents: deterministic zero-token writes, a first-class failure guard (never repeat a mistake), and a token-efficient briefing. Local CPU semantic recall — no API keys, no cloud.
+Author: Nahian
+License: PolyForm-Noncommercial-1.0.0
+Project-URL: Homepage, https://github.com/jabir-al-nahian/memir
+Project-URL: Repository, https://github.com/jabir-al-nahian/memir
+Project-URL: Issues, https://github.com/jabir-al-nahian/memir/issues
+Project-URL: Changelog, https://github.com/jabir-al-nahian/memir/blob/main/CHANGELOG.md
+Keywords: agent,memory,llm,coding-agent,mcp,model-context-protocol,failure-memory,context-window,local-first,rag,sqlite,embeddings,model2vec
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: model2vec>=0.3
+Requires-Dist: numpy>=1.21
+Provides-Extra: nli
+Requires-Dist: torch>=2.2; extra == "nli"
+Requires-Dist: transformers>=4.40; extra == "nli"
+Provides-Extra: rerank
+Requires-Dist: torch>=2.2; extra == "rerank"
+Requires-Dist: transformers>=4.40; extra == "rerank"
+Provides-Extra: contextual
+Requires-Dist: torch>=2.2; extra == "contextual"
+Requires-Dist: transformers>=4.40; extra == "contextual"
+Provides-Extra: ml
+Requires-Dist: torch>=2.2; extra == "ml"
+Requires-Dist: transformers>=4.40; extra == "ml"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# 🧠 Memir
+
+**The memoir your coding agent writes for itself.**
+Long-term memory for coding agents that *doesn't* eat your context window.
+Local-first. Zero API keys. And it **never lets the agent repeat a mistake.**
+
+[![CI](https://github.com/jabir-al-nahian/memir/actions/workflows/ci.yml/badge.svg)](https://github.com/jabir-al-nahian/memir/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License](https://img.shields.io/badge/license-PolyForm%20Noncommercial%201.0.0-orange)
+![Runs on CPU](https://img.shields.io/badge/runs%20on-CPU%20only-brightgreen)
+
+> *Memir* = **mem**ory + **memoir** + **Mímir**, the Norse keeper of memory and
+> wisdom. Your agent keeps a memoir; Memir is where it lives.
+
+---
+
+## The problem
+
+Every coding agent forgets. Switch chats, hit the context limit, start a new
+session — and it re-asks what it already knew, re-decides what you already
+decided, and **repeats the exact mistake it made an hour ago.**
+
+The common "fix" is to stuff the whole history back into the prompt every turn.
+That burns thousands of tokens per request and *still* overflows as the project
+grows.
+
+## The idea
+
+Memir stores three kinds of memory in a tiny local SQLite file:
+
+| kind | what it captures |
+|------|------------------|
+| **fact** | durable truths about the project (endpoints, conventions, constraints) |
+| **decision** | a choice **and the reason** for it, so it isn't relitigated |
+| **failure** | what was **tried**, **why it failed**, and the **lesson** — a first-class memory |
+
+Then it hands the agent a **token-budgeted briefing** at the start of a session
+and a **failure guard** it can check *before* trying something.
+
+> **Writing a memory costs 0 tokens and 0 API calls** — it's a local insert, sub-
+> millisecond. Compare that to memory frameworks that run an LLM extraction call
+> on *every* `add`.
+
+---
+
+## Why it's different
+
+- **First-class FAILURE memory.** Most memory tools remember facts. Memir
+  remembers *mistakes* — what failed, why, and what to do instead — and blocks
+  the repeat. That's the load-bearing feature for a coding agent.
+- **0-token, deterministic writes.** No LLM in the capture path. Nothing to bill,
+  nothing to rate-limit, nothing to go down.
+- **Local semantic recall by default.** Ships with a retrieval-tuned, numpy-only
+  embedding model ([model2vec](https://github.com/MinishLab/model2vec)
+  `potion-retrieval-32M`) that runs in ~1 ms on a **CPU** — no GPU, no torch, no
+  API. Paraphrase matching works out of the box, and gracefully falls back to
+  keyword recall if the model can't be loaded.
+- **Anti-bloat.** Write-time dedup plus a *safe* `consolidate()` that only merges
+  genuine restatements — it will **never** collapse two distinct facts.
+- **Bounded context cost.** A naive "replay everything" agent grows without
+  bound; the briefing here stays inside a token budget you set.
+- **Plugs into any agent via MCP.** One stdio server works with Cursor, Claude
+  Desktop, Cline, VS Code, Windsurf, …
+
+---
+
+## Install
+
+```bash
+pip install memir
+```
+
+The base install is light — `model2vec` + `numpy` only (no torch, no GPU, no
+API key). Optional **local CPU** accuracy features are opt-in extras:
+
+```bash
+pip install "memir[rerank]"      # cross-encoder reranker (precision second stage)
+pip install "memir[nli]"         # NLI reasoner (contradiction detection)
+pip install "memir[contextual]"  # contextual BGE encoder (stronger multi-hop)
+pip install "memir[ml]"          # all of the above
+```
+
+Warm the model cache once so later runs work fully offline:
+
+```bash
+memir setup      # downloads the CPU model, initialises the store
+memir start      # starts the MCP server (stdio) for your editor/agent
+```
+
+---
+
+## Quickstart (Python)
+
+```python
+from memir import Memir
+
+brain = Memir("my-project")          # local model loads automatically (CPU)
+
+# remember things (0 tokens, sub-ms, no API)
+brain.remember_fact("The billing job MUST run in UTC; our partner reports in UTC.")
+brain.record_decision("Use SQLite FTS5 for recall.", reason="100x faster than scanning.")
+
+# record a failure so it's never repeated
+brain.record_failure(
+    attempt="POSTed the whole batch to /v1/ingest in one request.",
+    reason="The gateway silently drops bodies >256KB and returns an empty 200.",
+    lesson="Chunk uploads under 256KB and verify each ack id.",
+)
+
+# BEFORE trying something, check the failure guard
+if hits := brain.check_failure("send the full batch to /v1/ingest at once"):
+    print("⛔", hits[0].lesson)   # -> Chunk uploads under 256KB and verify each ack id.
+
+# start a fresh session fully informed, within a token budget
+print(brain.briefing(budget_tokens=300))
+```
+
+### Auto-capture from real errors
+
+```python
+# parses the traceback, decides it's non-obvious, stores it as a failure:
+brain.capture_error("RuntimeError: gateway returned 200 with empty body — silently dropped")
+
+# a textbook typo is judged self-evident and skipped (no bloat):
+brain.capture_error("NameError: name 'foo' is not defined")   # -> None
+```
+
+---
+
+## Command line
+
+```bash
+memir remember "Deploys go out via the blue/green pipeline only."
+memir decision "Adopt SQLite WAL" --why "concurrent reads during writes"
+memir failure  "Dropped the prod table" --why "ran migration w/o backup" \
+               --lesson "snapshot before every migration"
+memir recall   "how do we deploy?"
+memir check    "run the migration now"      # failure guard
+memir briefing --budget 300
+memir stats
+memir doctor                                 # environment + MCP config check
+```
+
+---
+
+## Use it from your editor (MCP)
+
+Memir ships a Model Context Protocol server (stdio JSON-RPC).
+
+**Cursor / Windsurf / Claude Desktop** — add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "memir": {
+      "command": "memir",
+      "args": ["start"],
+      "env": { "MEMIR_PROJECT": "my-project", "MEMIR_DB": ".memir/memir.db" }
+    }
+  }
+}
+```
+
+**VS Code** (`.vscode/mcp.json`):
+
+```json
+{ "servers": { "memir": { "command": "memir", "args": ["start"] } } }
+```
+
+Tools exposed: `remember_fact`, `record_decision`, `record_failure`, `recall`,
+`check_failure`, `briefing`, `capture_error`, `stats`, `consolidate`.
+
+Set `MEMIR_EMBED=0` to force keyword-only mode (skips the model entirely).
+Override the model with `MEMIR_MODEL=minishlab/potion-base-8M` (30 MB, faster).
+
+---
+
+## Benchmarks
+
+Memir is measured against real memory backends (mem0, cognee, graphiti, letta)
+and an oracle upper bound under a single uniform LLM judge. The honest headline:
+**Memir matches the top accuracy tier while injecting ~10× fewer memory tokens
+per turn**, locally and with zero-token writes. See
+[docs/BENCHMARKS.md](docs/BENCHMARKS.md) for the full tables, the competitor
+head-to-heads, and the documented limits (relational multi-hop at large scale).
+
+---
+
+## License
+
+[PolyForm Noncommercial 1.0.0](LICENSE.md) — **free for research, personal,
+educational, and other noncommercial use.** Commercial use is reserved; for a
+commercial license, open an issue. (The author holds the copyright and may
+relicense more permissively in the future.)

memir-0.3.0/README.md

@@ -0,0 +1,194 @@
+# 🧠 Memir
+
+**The memoir your coding agent writes for itself.**
+Long-term memory for coding agents that *doesn't* eat your context window.
+Local-first. Zero API keys. And it **never lets the agent repeat a mistake.**
+
+[![CI](https://github.com/jabir-al-nahian/memir/actions/workflows/ci.yml/badge.svg)](https://github.com/jabir-al-nahian/memir/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License](https://img.shields.io/badge/license-PolyForm%20Noncommercial%201.0.0-orange)
+![Runs on CPU](https://img.shields.io/badge/runs%20on-CPU%20only-brightgreen)
+
+> *Memir* = **mem**ory + **memoir** + **Mímir**, the Norse keeper of memory and
+> wisdom. Your agent keeps a memoir; Memir is where it lives.
+
+---
+
+## The problem
+
+Every coding agent forgets. Switch chats, hit the context limit, start a new
+session — and it re-asks what it already knew, re-decides what you already
+decided, and **repeats the exact mistake it made an hour ago.**
+
+The common "fix" is to stuff the whole history back into the prompt every turn.
+That burns thousands of tokens per request and *still* overflows as the project
+grows.
+
+## The idea
+
+Memir stores three kinds of memory in a tiny local SQLite file:
+
+| kind | what it captures |
+|------|------------------|
+| **fact** | durable truths about the project (endpoints, conventions, constraints) |
+| **decision** | a choice **and the reason** for it, so it isn't relitigated |
+| **failure** | what was **tried**, **why it failed**, and the **lesson** — a first-class memory |
+
+Then it hands the agent a **token-budgeted briefing** at the start of a session
+and a **failure guard** it can check *before* trying something.
+
+> **Writing a memory costs 0 tokens and 0 API calls** — it's a local insert, sub-
+> millisecond. Compare that to memory frameworks that run an LLM extraction call
+> on *every* `add`.
+
+---
+
+## Why it's different
+
+- **First-class FAILURE memory.** Most memory tools remember facts. Memir
+  remembers *mistakes* — what failed, why, and what to do instead — and blocks
+  the repeat. That's the load-bearing feature for a coding agent.
+- **0-token, deterministic writes.** No LLM in the capture path. Nothing to bill,
+  nothing to rate-limit, nothing to go down.
+- **Local semantic recall by default.** Ships with a retrieval-tuned, numpy-only
+  embedding model ([model2vec](https://github.com/MinishLab/model2vec)
+  `potion-retrieval-32M`) that runs in ~1 ms on a **CPU** — no GPU, no torch, no
+  API. Paraphrase matching works out of the box, and gracefully falls back to
+  keyword recall if the model can't be loaded.
+- **Anti-bloat.** Write-time dedup plus a *safe* `consolidate()` that only merges
+  genuine restatements — it will **never** collapse two distinct facts.
+- **Bounded context cost.** A naive "replay everything" agent grows without
+  bound; the briefing here stays inside a token budget you set.
+- **Plugs into any agent via MCP.** One stdio server works with Cursor, Claude
+  Desktop, Cline, VS Code, Windsurf, …
+
+---
+
+## Install
+
+```bash
+pip install memir
+```
+
+The base install is light — `model2vec` + `numpy` only (no torch, no GPU, no
+API key). Optional **local CPU** accuracy features are opt-in extras:
+
+```bash
+pip install "memir[rerank]"      # cross-encoder reranker (precision second stage)
+pip install "memir[nli]"         # NLI reasoner (contradiction detection)
+pip install "memir[contextual]"  # contextual BGE encoder (stronger multi-hop)
+pip install "memir[ml]"          # all of the above
+```
+
+Warm the model cache once so later runs work fully offline:
+
+```bash
+memir setup      # downloads the CPU model, initialises the store
+memir start      # starts the MCP server (stdio) for your editor/agent
+```
+
+---
+
+## Quickstart (Python)
+
+```python
+from memir import Memir
+
+brain = Memir("my-project")          # local model loads automatically (CPU)
+
+# remember things (0 tokens, sub-ms, no API)
+brain.remember_fact("The billing job MUST run in UTC; our partner reports in UTC.")
+brain.record_decision("Use SQLite FTS5 for recall.", reason="100x faster than scanning.")
+
+# record a failure so it's never repeated
+brain.record_failure(
+    attempt="POSTed the whole batch to /v1/ingest in one request.",
+    reason="The gateway silently drops bodies >256KB and returns an empty 200.",
+    lesson="Chunk uploads under 256KB and verify each ack id.",
+)
+
+# BEFORE trying something, check the failure guard
+if hits := brain.check_failure("send the full batch to /v1/ingest at once"):
+    print("⛔", hits[0].lesson)   # -> Chunk uploads under 256KB and verify each ack id.
+
+# start a fresh session fully informed, within a token budget
+print(brain.briefing(budget_tokens=300))
+```
+
+### Auto-capture from real errors
+
+```python
+# parses the traceback, decides it's non-obvious, stores it as a failure:
+brain.capture_error("RuntimeError: gateway returned 200 with empty body — silently dropped")
+
+# a textbook typo is judged self-evident and skipped (no bloat):
+brain.capture_error("NameError: name 'foo' is not defined")   # -> None
+```
+
+---
+
+## Command line
+
+```bash
+memir remember "Deploys go out via the blue/green pipeline only."
+memir decision "Adopt SQLite WAL" --why "concurrent reads during writes"
+memir failure  "Dropped the prod table" --why "ran migration w/o backup" \
+               --lesson "snapshot before every migration"
+memir recall   "how do we deploy?"
+memir check    "run the migration now"      # failure guard
+memir briefing --budget 300
+memir stats
+memir doctor                                 # environment + MCP config check
+```
+
+---
+
+## Use it from your editor (MCP)
+
+Memir ships a Model Context Protocol server (stdio JSON-RPC).
+
+**Cursor / Windsurf / Claude Desktop** — add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "memir": {
+      "command": "memir",
+      "args": ["start"],
+      "env": { "MEMIR_PROJECT": "my-project", "MEMIR_DB": ".memir/memir.db" }
+    }
+  }
+}
+```
+
+**VS Code** (`.vscode/mcp.json`):
+
+```json
+{ "servers": { "memir": { "command": "memir", "args": ["start"] } } }
+```
+
+Tools exposed: `remember_fact`, `record_decision`, `record_failure`, `recall`,
+`check_failure`, `briefing`, `capture_error`, `stats`, `consolidate`.
+
+Set `MEMIR_EMBED=0` to force keyword-only mode (skips the model entirely).
+Override the model with `MEMIR_MODEL=minishlab/potion-base-8M` (30 MB, faster).
+
+---
+
+## Benchmarks
+
+Memir is measured against real memory backends (mem0, cognee, graphiti, letta)
+and an oracle upper bound under a single uniform LLM judge. The honest headline:
+**Memir matches the top accuracy tier while injecting ~10× fewer memory tokens
+per turn**, locally and with zero-token writes. See
+[docs/BENCHMARKS.md](docs/BENCHMARKS.md) for the full tables, the competitor
+head-to-heads, and the documented limits (relational multi-hop at large scale).
+
+---
+
+## License
+
+[PolyForm Noncommercial 1.0.0](LICENSE.md) — **free for research, personal,
+educational, and other noncommercial use.** Commercial use is reserved; for a
+commercial license, open an issue. (The author holds the copyright and may
+relicense more permissively in the future.)