breathing-memory 0.1.0__tar.gz

breathing_memory-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KazinaG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

breathing_memory-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: breathing-memory
+Version: 0.1.0
+Summary: Local Codex memory manager with an official Python SDK-based MCP server.
+Author: OpenAI Codex
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/KazinaG/breathing_memory
+Project-URL: Repository, https://github.com/KazinaG/breathing_memory
+Keywords: codex,mcp,memory,sqlite,agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<2,>=1.26
+Requires-Dist: platformdirs<5,>=4
+Dynamic: license-file
+
+# Breathing Memory
+
+Breathing Memory is a local memory support system for coding agents. It runs as a stdio MCP server through the official Python MCP SDK, stores memory in SQLite, and isolates memory by project so one installation can be reused across repositories without mixing contexts.
+
+## Overview
+
+Breathing Memory keeps collaboration context that an agent should remember but a repository should not need to encode everywhere.
+
+- local stdio MCP server
+- SQLite storage under user app-data, isolated by project
+- fragment-centric public model built around `anchor` and `fragment`
+- text-first retrieval today, with a public search surface already aligned for later semantic retrieval work
+- dynamic `working / holding` maintenance with a compression backend that uses a supported coding agent without polluting normal conversation history
+
+## Supported Clients
+
+- Codex
+
+## Installation
+
+The intended long-term user path is:
+
+```bash
+pip install breathing-memory
+breathing-memory install-codex
+```
+
+`breathing-memory install-codex` registers the `breathing-memory` MCP server with the currently supported client and creates or updates the managed Breathing Memory block in the current repository's `AGENTS.md`.
+
+This repository is configured for tag-based PyPI publishing through GitHub Actions. Until the first public release is published, install from Git or from a local clone:
+
+```bash
+pip install git+https://github.com/KazinaG/breathing_memory.git
+# or inside a clone:
+pip install -e .
+breathing-memory install-codex
+```
+
+Release notes:
+
+- PyPI publish runs from `.github/workflows/publish.yml`
+- pushing a tag such as `v0.1.0` triggers the build and PyPI publish workflow
+
+## Quickstart
+
+Recommended first run:
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+pip install -e .
+breathing-memory doctor
+breathing-memory install-codex
+```
+
+Useful commands:
+
+- `breathing-memory doctor`: inspect installation, active project identity, DB path selection, and client registration state
+- `breathing-memory serve`: start the stdio MCP server
+- `breathing-memory inspect-memory --json`: inspect current memory state
+
+## How Memory Works
+
+Breathing Memory does not auto-capture the full client conversation by itself. The supported operating path is explicit MCP use by the calling agent.
+
+The basic flow is:
+
+1. If there is an unremembered final agent answer from the previous turn, save it first with `memory_remember(actor="agent")`
+2. Save the current user message with `memory_remember(actor="user")`
+3. Search before an answer with `memory_search`
+4. Record feedback with `memory_feedback` when the user clearly confirms or corrects remembered information
+
+Key points:
+
+- one user utterance becomes one fragment
+- one final user-facing agent answer is normally remembered on the next user turn
+- commentary is not remembered
+- if the final answer materially used remembered fragments, pass those ids in `source_fragment_ids`
+- edits are modeled as forks rather than overwrites
+- duplicate deferred agent capture for the same reply target and content is suppressed
+- archived runtime files such as `archived_sessions/*.jsonl` are not the primary capture path
+- if no later user turn arrives, the final agent answer may remain unremembered
+
+Current MCP tools:
+
+- `memory_remember`
+- `memory_search`
+- `memory_fetch`
+- `memory_feedback`
+- `memory_stats`
+
+## Runtime Notes
+
+Breathing Memory stores data under the user app-data directory resolved by `platformdirs`, then separates memory by project identity. The exact SQLite path can be inspected with `breathing-memory doctor`.
+
+The current implementation is text-only. Runtime `auto` resolves to `super_lite`, which performs lexical retrieval only. The public search surface is already aligned for later semantic retrieval work, but explicit `lite` and `default` modes are not supported in this slice.
+
+The current compression backend invokes a supported coding agent without leaving normal conversation history. In the current supported setup, that path uses Codex through `codex exec --ephemeral`.
+
+## Further Reading
+
+- [docs/user-guide.md](docs/user-guide.md): installation, runtime operation, storage behavior, and MCP tool usage
+- [docs/dev-guide.md](docs/dev-guide.md): contributor-oriented setup and repository layout
+- [docs/spec.md](docs/spec.md): normative behavior and implementation-facing rules
+- [docs/design-rationale.md](docs/design-rationale.md): adopted design choices and the reasons behind them

breathing_memory-0.1.0/README.md

@@ -0,0 +1,105 @@
+# Breathing Memory
+
+Breathing Memory is a local memory support system for coding agents. It runs as a stdio MCP server through the official Python MCP SDK, stores memory in SQLite, and isolates memory by project so one installation can be reused across repositories without mixing contexts.
+
+## Overview
+
+Breathing Memory keeps collaboration context that an agent should remember but a repository should not need to encode everywhere.
+
+- local stdio MCP server
+- SQLite storage under user app-data, isolated by project
+- fragment-centric public model built around `anchor` and `fragment`
+- text-first retrieval today, with a public search surface already aligned for later semantic retrieval work
+- dynamic `working / holding` maintenance with a compression backend that uses a supported coding agent without polluting normal conversation history
+
+## Supported Clients
+
+- Codex
+
+## Installation
+
+The intended long-term user path is:
+
+```bash
+pip install breathing-memory
+breathing-memory install-codex
+```
+
+`breathing-memory install-codex` registers the `breathing-memory` MCP server with the currently supported client and creates or updates the managed Breathing Memory block in the current repository's `AGENTS.md`.
+
+This repository is configured for tag-based PyPI publishing through GitHub Actions. Until the first public release is published, install from Git or from a local clone:
+
+```bash
+pip install git+https://github.com/KazinaG/breathing_memory.git
+# or inside a clone:
+pip install -e .
+breathing-memory install-codex
+```
+
+Release notes:
+
+- PyPI publish runs from `.github/workflows/publish.yml`
+- pushing a tag such as `v0.1.0` triggers the build and PyPI publish workflow
+
+## Quickstart
+
+Recommended first run:
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+pip install -e .
+breathing-memory doctor
+breathing-memory install-codex
+```
+
+Useful commands:
+
+- `breathing-memory doctor`: inspect installation, active project identity, DB path selection, and client registration state
+- `breathing-memory serve`: start the stdio MCP server
+- `breathing-memory inspect-memory --json`: inspect current memory state
+
+## How Memory Works
+
+Breathing Memory does not auto-capture the full client conversation by itself. The supported operating path is explicit MCP use by the calling agent.
+
+The basic flow is:
+
+1. If there is an unremembered final agent answer from the previous turn, save it first with `memory_remember(actor="agent")`
+2. Save the current user message with `memory_remember(actor="user")`
+3. Search before an answer with `memory_search`
+4. Record feedback with `memory_feedback` when the user clearly confirms or corrects remembered information
+
+Key points:
+
+- one user utterance becomes one fragment
+- one final user-facing agent answer is normally remembered on the next user turn
+- commentary is not remembered
+- if the final answer materially used remembered fragments, pass those ids in `source_fragment_ids`
+- edits are modeled as forks rather than overwrites
+- duplicate deferred agent capture for the same reply target and content is suppressed
+- archived runtime files such as `archived_sessions/*.jsonl` are not the primary capture path
+- if no later user turn arrives, the final agent answer may remain unremembered
+
+Current MCP tools:
+
+- `memory_remember`
+- `memory_search`
+- `memory_fetch`
+- `memory_feedback`
+- `memory_stats`
+
+## Runtime Notes
+
+Breathing Memory stores data under the user app-data directory resolved by `platformdirs`, then separates memory by project identity. The exact SQLite path can be inspected with `breathing-memory doctor`.
+
+The current implementation is text-only. Runtime `auto` resolves to `super_lite`, which performs lexical retrieval only. The public search surface is already aligned for later semantic retrieval work, but explicit `lite` and `default` modes are not supported in this slice.
+
+The current compression backend invokes a supported coding agent without leaving normal conversation history. In the current supported setup, that path uses Codex through `codex exec --ephemeral`.
+
+## Further Reading
+
+- [docs/user-guide.md](docs/user-guide.md): installation, runtime operation, storage behavior, and MCP tool usage
+- [docs/dev-guide.md](docs/dev-guide.md): contributor-oriented setup and repository layout
+- [docs/spec.md](docs/spec.md): normative behavior and implementation-facing rules
+- [docs/design-rationale.md](docs/design-rationale.md): adopted design choices and the reasons behind them

breathing_memory-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "breathing-memory"
+version = "0.1.0"
+description = "Local Codex memory manager with an official Python SDK-based MCP server."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "OpenAI Codex" }]
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["mcp>=1.26,<2", "platformdirs>=4,<5"]
+keywords = ["codex", "mcp", "memory", "sqlite", "agent"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development",
+]
+
+[project.urls]
+Homepage = "https://github.com/KazinaG/breathing_memory"
+Repository = "https://github.com/KazinaG/breathing_memory"
+
+[project.scripts]
+breathing-memory = "breathing_memory.__main__:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

breathing_memory-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

breathing_memory-0.1.0/src/breathing_memory/__init__.py

@@ -0,0 +1,23 @@
+from .cli import main
+from .compression import CodexExecCompressionBackend, CompressionBackend, StubCompressionBackend
+from .config import EngineTuning, MemoryConfig
+from .engine import BreathingMemoryEngine
+from .mcp_server import create_mcp_server, serve_stdio, serve_stdio_server
+from .runtime import resolve_db_path, resolve_project_identity
+from .store import SQLiteStore
+
+__all__ = [
+    "BreathingMemoryEngine",
+    "CodexExecCompressionBackend",
+    "CompressionBackend",
+    "EngineTuning",
+    "MemoryConfig",
+    "SQLiteStore",
+    "StubCompressionBackend",
+    "create_mcp_server",
+    "main",
+    "resolve_db_path",
+    "resolve_project_identity",
+    "serve_stdio",
+    "serve_stdio_server",
+]

breathing_memory-0.1.0/src/breathing_memory/__main__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())