observational-memory 0.1.0__tar.gz

observational_memory-0.1.0/.claude/settings.local.json

@@ -0,0 +1,20 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(om search:*)",
+      "Bash(uv run pytest:*)",
+      "Bash(bun:*)",
+      "Bash(qmd --help:*)",
+      "Bash(qmd status:*)",
+      "Bash(qmd embed:*)",
+      "Bash(qmd query:*)",
+      "Bash(qmd search:*)",
+      "Bash(git add:*)",
+      "Bash(git commit -m \"$\\(cat <<''EOF''\nAdd qmd-hybrid backend for vector + LLM reranked search\n\nAdds \"qmd-hybrid\" as a new pluggable search backend that uses QMD''s\n`query` command \\(BM25 + vector embeddings + LLM reranking\\) instead of\nplain `search`. Also fixes QMD result parsing to handle qmd:// URLs\nand snippet fallback.\n\nCo-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>\nEOF\n\\)\")",
+      "Bash(git push:*)",
+      "Bash(uv run python:*)",
+      "Bash(git commit -m \"$\\(cat <<''EOF''\nAdd OM_SEARCH_BACKEND env var to configure search backend\n\nThe search backend can now be set via OM_SEARCH_BACKEND in the env\nfile \\(~/.config/observational-memory/env\\) or as an environment\nvariable, instead of editing config.py. Default remains bm25.\n\nCo-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>\nEOF\n\\)\")",
+      "Bash(om:*)"
+    ]
+  }
+}

observational_memory-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+      fail-fast: false
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+
+      - name: Test
+        run: uv run pytest -q

observational_memory-0.1.0/.github/workflows/claude-code-review.yml

@@ -0,0 +1,44 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, ready_for_review, reopened]
+    # Optional: Only run on specific file changes
+    # paths:
+    #   - "src/**/*.ts"
+    #   - "src/**/*.tsx"
+    #   - "src/**/*.js"
+    #   - "src/**/*.jsx"
+
+jobs:
+  claude-review:
+    # Optional: Filter by PR author
+    # if: |
+    #   github.event.pull_request.user.login == 'external-contributor' ||
+    #   github.event.pull_request.user.login == 'new-developer' ||
+    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
+          plugins: 'code-review@claude-code-plugins'
+          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://code.claude.com/docs/en/cli-reference for available options
+

observational_memory-0.1.0/.github/workflows/claude.yml

@@ -0,0 +1,50 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://code.claude.com/docs/en/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr:*)'
+

observational_memory-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+
+# Memory files (generated locally)
+memory/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# macOS
+.DS_Store
+
+# uv
+uv.lock

observational_memory-0.1.0/CLAUDE.md

@@ -0,0 +1,64 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Test
+
+```bash
+# Makefile targets (preferred)
+make check              # lint + test (run before committing)
+make test               # tests only
+make lint               # ruff check + format check
+make format             # auto-format code
+make build              # build sdist + wheel
+make clean              # remove build artifacts
+make bump-version       # bump patch (BUMP=minor|major)
+make publish-test       # publish to TestPyPI
+make publish            # publish to PyPI (production)
+make install-dev        # editable install with dev deps
+make doctor             # run om doctor diagnostics
+
+# Direct commands
+uv sync                          # install deps
+uv run pytest                    # run all tests
+uv run pytest tests/test_transcripts.py  # single test file
+uv run pytest -v                 # verbose
+uv run om status                 # check local installation status
+uv run om doctor                 # run diagnostics
+```
+
+## Architecture
+
+Cross-agent observational memory that works at the **user level** (not per-project) across Claude Code and Codex CLI. Two background processes compress conversation transcripts into shared memory files at `~/.local/share/observational-memory/`.
+
+### Data flow
+
+```
+Transcripts (Claude JSONL / Codex sessions)
+  → observe.py (LLM compression → observations.md)
+  → reflect.py (daily consolidation → reflections.md)
+```
+
+### Key modules
+
+- **`src/observational_memory/transcripts/claude.py`** — Parses Claude Code `.jsonl` transcripts. Each line is a JSON object with `type` (user/assistant/progress), `message.content` (text or array of blocks), `uuid`, `timestamp`.
+- **`src/observational_memory/transcripts/codex.py`** — Parses Codex CLI session files (`*.json` and `*.jsonl`) from `~/.codex/sessions/`.
+- **`src/observational_memory/observe.py`** — Observer: reads transcripts, finds new messages via cursor bookmarks, calls LLM to compress, appends to `observations.md`.
+- **`src/observational_memory/reflect.py`** — Reflector: reads observations + reflections, calls LLM to condense, writes `reflections.md`, trims old observations.
+- **`src/observational_memory/llm.py`** — Thin abstraction over Anthropic and OpenAI APIs. Auto-detects provider from env vars.
+- **`src/observational_memory/config.py`** — All paths, defaults, cursor management. Memory dir follows XDG spec. Search backend is configurable via `OM_SEARCH_BACKEND` env var.
+- **`src/observational_memory/cli.py`** — Click CLI (`om` command). Commands: observe, reflect, backfill, search, context, install, uninstall, status, doctor.
+- **`src/observational_memory/search/`** — Pluggable search over memory files. BM25 backend (default, uses `rank-bm25`), QMD backend (optional, shells out to `qmd` CLI — `"qmd"` for keyword search, `"qmd-hybrid"` for hybrid BM25 + vector + LLM reranking), None backend (no-op). Parser splits observations by date, reflections by section. The `reindex()` orchestrator is called automatically after observe/reflect writes.
+
+### Agent integration
+
+- **Claude Code**: `SessionStart` injects memory via `additionalContext`; `SessionEnd`, `UserPromptSubmit`, and `PreCompact` hooks trigger checkpoints. In-session checkpoints are throttled by `OM_SESSION_OBSERVER_INTERVAL_SECONDS` and can be disabled with `OM_DISABLE_SESSION_OBSERVER_CHECKPOINTS`.
+- **Codex CLI**: Instructions appended to `~/.codex/AGENTS.md`; cron job for observer.
+
+### API keys
+
+API keys live in `~/.config/observational-memory/env` (created by `om install`, chmod 600). The CLI loads this file on startup via `config.load_env_file()`. The Claude hooks and cron jobs also source it. Environment variables take precedence over the file.
+
+### Prompts
+
+`src/observational_memory/prompts/observer.md` and `src/observational_memory/prompts/reflector.md` define the LLM system prompts. They are bundled as package data. The priority system (🔴/🟡/🟢) and output format are critical — downstream parsing depends on them.

observational_memory-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Intertwine
+
+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.

observational_memory-0.1.0/Makefile

@@ -0,0 +1,125 @@
+# Makefile for observational-memory
+# Cross-agent shared memory for Claude Code and Codex CLI
+
+SHELL := /bin/bash
+
+.PHONY: help test lint format check build clean bump-version publish-test publish install-dev doctor
+
+# ---------- Colors (portable) ----------
+ifdef NO_COLOR
+RED :=
+GREEN :=
+YELLOW :=
+NC :=
+else
+ESC := $(shell printf '\033')
+RED := $(ESC)[0;31m
+GREEN := $(ESC)[0;32m
+YELLOW := $(ESC)[1;33m
+NC := $(ESC)[0m
+endif
+ECHO = printf "%b\n"
+
+# Version bump type (patch, minor, major)
+BUMP ?= patch
+
+help:
+	@$(ECHO) "$(GREEN)Observational Memory - Development Commands$(NC)"
+	@$(ECHO) ""
+	@$(ECHO) "$(YELLOW)Quality:$(NC)"
+	@$(ECHO) "  make test           - Run all tests"
+	@$(ECHO) "  make lint           - Run linter checks"
+	@$(ECHO) "  make format         - Auto-format code"
+	@$(ECHO) "  make check          - Run all quality checks (lint + format check + test)"
+	@$(ECHO) ""
+	@$(ECHO) "$(YELLOW)Building:$(NC)"
+	@$(ECHO) "  make build          - Build sdist and wheel"
+	@$(ECHO) "  make clean          - Remove build artifacts"
+	@$(ECHO) ""
+	@$(ECHO) "$(YELLOW)Versioning:$(NC)"
+	@$(ECHO) "  make bump-version              - Bump patch version (default)"
+	@$(ECHO) "  make bump-version BUMP=minor   - Bump minor version"
+	@$(ECHO) "  make bump-version BUMP=major   - Bump major version"
+	@$(ECHO) ""
+	@$(ECHO) "$(YELLOW)Publishing:$(NC)"
+	@$(ECHO) "  make publish-test   - Publish to TestPyPI"
+	@$(ECHO) "  make publish        - Publish to PyPI (production)"
+	@$(ECHO) ""
+	@$(ECHO) "$(YELLOW)Development:$(NC)"
+	@$(ECHO) "  make install-dev    - Install in editable mode with dev deps"
+	@$(ECHO) "  make doctor         - Run om doctor diagnostics"
+
+# Run all tests
+test:
+	@$(ECHO) "$(YELLOW)Running tests...$(NC)"
+	@uv run pytest -q
+	@$(ECHO) "$(GREEN)✓ Tests passed$(NC)"
+
+# Run linter checks
+lint:
+	@$(ECHO) "$(YELLOW)Running linter...$(NC)"
+	@uv run ruff check .
+	@uv run ruff format --check .
+	@$(ECHO) "$(GREEN)✓ Lint passed$(NC)"
+
+# Auto-format code
+format:
+	@$(ECHO) "$(YELLOW)Formatting code...$(NC)"
+	@uv run ruff check . --fix
+	@uv run ruff format .
+	@$(ECHO) "$(GREEN)✓ Code formatted$(NC)"
+
+# Run all quality checks
+check: lint test
+	@$(ECHO) "$(GREEN)✓ All checks passed$(NC)"
+
+# Build sdist and wheel
+build: clean
+	@$(ECHO) "$(YELLOW)Building package...$(NC)"
+	@uv run python -m build
+	@$(ECHO) "$(GREEN)✓ Package built$(NC)"
+	@ls -lh dist/
+
+# Clean build artifacts
+clean:
+	@$(ECHO) "$(YELLOW)Cleaning build artifacts...$(NC)"
+	@rm -rf dist/ build/ src/*.egg-info
+	@find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+	@find . -type d -name ".pytest_cache" -exec rm -rf {} + 2>/dev/null || true
+	@find . -type d -name ".ruff_cache" -exec rm -rf {} + 2>/dev/null || true
+	@$(ECHO) "$(GREEN)✓ Clean$(NC)"
+
+# Bump version
+bump-version:
+	@if [ "$(BUMP)" != "patch" ] && [ "$(BUMP)" != "minor" ] && [ "$(BUMP)" != "major" ]; then \
+		$(ECHO) "$(RED)Error: BUMP must be 'patch', 'minor', or 'major'$(NC)"; \
+		exit 1; \
+	fi
+	@$(ECHO) "$(YELLOW)Bumping $(BUMP) version...$(NC)"
+	@VERSION_CHANGE=$$(uv run python scripts/bump_version.py pyproject.toml $(BUMP)); \
+	$(ECHO) "$(GREEN)✓ Version updated: $$VERSION_CHANGE$(NC)"
+
+# Publish to TestPyPI
+publish-test: build
+	@$(ECHO) "$(YELLOW)Publishing to TestPyPI...$(NC)"
+	@uv run twine upload --repository testpypi dist/*
+	@$(ECHO) "$(GREEN)✓ Published to TestPyPI$(NC)"
+	@$(ECHO) "$(YELLOW)Install with: uv tool install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ observational-memory$(NC)"
+
+# Publish to PyPI (production)
+publish: build
+	@$(ECHO) "$(RED)⚠️  Publishing to production PyPI!$(NC)"
+	@$(ECHO) -n "Continue? [y/N] " && read ans && ( [ "$${ans}" = "y" ] || [ "$${ans}" = "Y" ] )
+	@uv run twine upload dist/*
+	@$(ECHO) "$(GREEN)✓ Published to PyPI$(NC)"
+
+# Install in editable mode with dev dependencies
+install-dev:
+	@$(ECHO) "$(YELLOW)Installing in editable mode...$(NC)"
+	@uv sync
+	@uv pip install -e ".[dev]"
+	@$(ECHO) "$(GREEN)✓ Installed$(NC)"
+
+# Run diagnostics
+doctor:
+	@uv run om doctor