Metadata-Version: 2.4
Name: ocm-session-memory
Version: 0.1.0
Summary: Persistent local session memory for AI coding assistants via MCP and CLI.
Project-URL: Homepage, https://github.com/AchintyaX/OpenCodeMemory
Project-URL: Repository, https://github.com/AchintyaX/OpenCodeMemory
Project-URL: Issues, https://github.com/AchintyaX/OpenCodeMemory/issues
Project-URL: Changelog, https://github.com/AchintyaX/OpenCodeMemory/releases
Author-email: Achintya Shankhdhar <achintyashankhdhar@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Achintya Shankhdhar
        
        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.
License-File: LICENSE
Keywords: ai-coding,claude-code,cursor,llm,mcp,memory
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: gitpython>=3.1
Requires-Dist: mcp[cli]>=1.0
Requires-Dist: python-dateutil>=2.9
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# openCodeMemory

**Persistent session memory for AI coding assistants. Local. Private. Zero cloud.**

AI coding assistants lose all context when a session ends — what you were building, decisions made, files changed. openCodeMemory solves this by capturing session state as structured markdown files, indexing them with SQLite FTS5 for fast search, and exposing them via MCP so your assistant can pick up exactly where it left off.

---

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                    IDE (Claude Code / Cursor)                     │
│                                                                   │
│  ┌──────────────┐  MCP         ┌───────────────────────────────┐   │
│  │  AI Model    │──────────▶   │  ocm.server (FastMCP)         │   │
│  │  (checkpoint │  (stdio)     │  ocm__checkpoint              │   │
│  │   / search)  │◀──────────   │  ocm__search_sessions         │   │
│  └──────────────┘  result      │  ocm__list_sessions           │   │
│                                 │  ocm__get_session_files       │   │
│                                 └──────────────┬────────────────┘   │
└───────────────────────────────────────────────┼────────────────────┘
                                                │
              ┌─────────────────────────────────▼──────────────────┐
              │          .openCodeMemory/  (per-project)            │
              │                                                      │
              │  sessions/                                           │
              │  └── 2026-03-03_14-32_claude-code_auth-fix.md  ◀── canonical source
              │                                                      │
              │  memory.db  (SQLite)                                 │
              │  ├── sessions       (metadata)                       │
              │  ├── session_chunks (goal, decisions, work…)         │
              │  ├── session_files  (touched files list)             │
              │  └── sessions_fts   (FTS5 BM25 search index)         │
              │                                                      │
              │  active_<session_id>.jsonl  (file-edit journal)      │
              └──────────────────────────────────────────────────────┘
```

**Hook usage** — Hooks are profile-driven. Claude defaults to a minimal hook profile; Cursor defaults to no hooks unless enabled. Both assistants can use a shared `postToolUse` semantic-checkpoint policy (threshold: 5 tool calls).

**Active MCP tool flow** — the AI assistant calls `ocm__checkpoint` to persist a snapshot and `ocm__search_sessions` to retrieve past context. Search returns a `markdown_path`; the assistant reads the file directly.

---

## Prerequisites

- Python 3.11+
- `[uv](https://docs.astral.sh/uv/)` (recommended) or `pip`
- Claude Code CLI (`claude`) and/or Cursor installed

---

## Installation

### From PyPI (recommended)

```bash
pip install ocm-session-memory
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv tool install ocm-session-memory
```

After installing, `ocm` and `ocm-hook` are available directly on your PATH.

### From source

```bash
git clone https://github.com/AchintyaX/OpenCodeMemory
cd OpenCodeMemory
uv sync
uv run ocm --help
```

### Quick start

```bash
pip install ocm-session-memory
ocm install                    # one-time global config — works in every project
# Open Claude Code or Cursor and ask it to "save a checkpoint"
```

---

## Safety & merge behavior

openCodeMemory writes into your existing IDE configuration. It is designed to be safe to run against a setup you already use:

- **Idempotent** — rule injections are wrapped in `<!-- BEGIN openCodeMemory -->` / `<!-- END openCodeMemory -->` sentinel markers. Re-running `ocm init` finds and replaces the existing block; it never duplicates content. Hook entries are only appended when the exact command isn't already present.
- **Atomic writes** — every `settings.json`, `CLAUDE.md`, and `.cursorrules` mutation goes through a temp-file + `os.replace()`, so an interrupted install never leaves a truncated config.
- **Fail-loud on bad JSON** — if `.claude/settings.json` (or any other JSON file we touch) is malformed when we try to read it, `ocm install` aborts with a clear error message rather than silently rewriting the file. Your existing config is never discarded on a parse error.
- **Versioned `.mdc` rule** — `.cursor/rules/ocm-checkpoint.mdc` ships with an `ocm-version:` frontmatter field. Future upgrades refresh it only when the version changes; user-modified copies with a different (or missing) version are left untouched.

---

## Global Installation (Recommended)

Run once, works in every project. This creates the default global store at `~/.openCodeMemory/memory.db` (project-local DBs created by `ocm init` still take precedence).

```bash
ocm install
# or: uv run ocm install
```

This creates global storage and configures detected assistants:

- **Storage**: `~/.openCodeMemory/memory.db` + `~/.openCodeMemory/sessions/`
- **Claude Code**:
  - MCP at user scope (`claude mcp add --scope user ...`)
  - Hook entry in `~/.claude/settings.json` (`UserPromptSubmit`)
  - Rules injected into `~/.claude/CLAUDE.md`
- **Cursor**:
  - MCP in `~/.cursor/mcp.json`
  - Global rules injection is not supported (add rules per project)

After `ocm install`, you can use openCodeMemory immediately across projects.
If you use Cursor and want persistent assistant guidance, run `ocm init` in a project (or add rules manually there).

**DB fallback priority**: per-project `.openCodeMemory/memory.db` (if present from `ocm init`) → global `~/.openCodeMemory/memory.db`.

---

## Project Setup — Optional

> Use `ocm init` if you want an isolated per-project DB instead of the global one.

Navigate to any project directory and run:

```bash
cd /path/to/your-project
ocm init
```

`ocm init` does all of the following automatically:

1. Detects the project root (walks up to `.git`)
2. Creates `.openCodeMemory/memory.db` and `sessions/` directory
3. Adds `.openCodeMemory/` to `.gitignore`
4. Detects installed assistants (Claude Code, Cursor)
5. For each assistant: registers MCP, configures selected hook profile, and injects usage rules
6. For Cursor projects: writes `.cursor/rules/ocm-checkpoint.mdc`
7. Registers the project in `~/.openCodeMemory/registry.json`

---

## Claude Code Setup

`ocm init` handles this automatically. By default, Claude uses `--claude-hooks minimal`.

**MCP server** registered at project scope:

```bash
claude mcp add --scope project opencodememory -- uv run python -m ocm.server
```

> If you installed via `pip install ocm-session-memory` without `uv`, replace `uv run python` with `python`.

**Hooks** written to `.claude/settings.json` (profile-dependent):


| Event | Purpose |
| --- | --- |
| `SessionStart` | Initializes session row via `ocm-hook session-start` |
| `UserPromptSubmit` | Injects `CLAUDE_SESSION_ID` reminder context |
| `PreToolUse` | Blocks tool calls when semantic checkpoint is stale |
| `PostToolUse` | Increments checkpoint counter and writes machine checkpoint |
| `Stop` | Marks session closed via `ocm-hook session-end` |


Notes:

- `--claude-hooks full` additionally records file edits with `ocm-hook file-edited`.
- Semantic checkpoint enforcement is hybrid: reminder first, then gate via `PreToolUse` after threshold is exceeded.

**Rules** are appended to `CLAUDE.md` inside `<!-- BEGIN openCodeMemory -->` / `<!-- END openCodeMemory -->` markers.

---

## Cursor Setup

`ocm init` handles this automatically. Cursor hooks are opt-in (`--cursor-hooks minimal|full`).

**MCP server** registered in `.cursor/mcp.json`.

**Hooks** are profile-based:
- `none` (default): no Cursor hook setup
- `minimal`: `sessionStart`, `preToolUse`, `postToolUse`, `stop`
- `full`: `minimal` plus `afterFileEdit` journal tracking

**Rules**:

- Appends openCodeMemory guidance to `.cursorrules` (inside sentinel markers)
- Writes `.cursor/rules/ocm-checkpoint.mdc` for always-on checkpoint instructions in Cursor

---

## Usage

### CLI Commands

```bash
ocm install                 # One-time global setup for detected assistants
ocm init                    # Optional project-local setup + project rules
ocm help                    # List all ocm commands with descriptions
ocm checkpoint              # Write/update session checkpoint from CLI
ocm list                    # List recent sessions (default: last 10)
ocm list --limit 20         # Last 20 sessions
ocm list --tool claude-code # Filter by tool
ocm search "Redis caching"  # BM25 natural language search
ocm show <session_id>       # Print full session markdown
ocm export <session_id>     # Copy markdown path to clipboard
ocm rebuild-index           # Rebuild FTS5 from session_chunks
ocm uninstall               # Remove OCM hooks/rules from project config (storage preserved)
ocm uninstall --global      # Remove OCM global hooks/rules (storage preserved)
```

### MCP Tools (called automatically by the AI assistant)


| Tool                     | When it's called                                   |
| ------------------------ | -------------------------------------------------- |
| `ocm__checkpoint`        | At ~70% context, before git commit, at task end    |
| `ocm__search_sessions`   | When user asks to continue previous work           |
| `ocm__list_sessions`     | To browse recent sessions                          |
| `ocm__get_session_files` | To get a session's file list without full markdown |


### Session Lifecycle

1. **Session identity established**
  - Claude: `UserPromptSubmit` injects `CLAUDE_SESSION_ID` into model context
  - Claude/Cursor: first `ocm__checkpoint` call can auto-create the session row
2. **File edits tracked**
  - At checkpoint time, journal entries are flushed when present
  - If no journal entries exist, checkpoint falls back to git diff from `git_sha_start`
3. **Checkpoint persisted**
  - `ocm__checkpoint` writes chunks, flushes journal when present, re-renders markdown, and rebuilds FTS
4. **Session closed**
  - Claude/Cursor: assistant can explicitly close with `ocm__checkpoint(..., status="closed")`

5. **Semantic checkpoint policy (when hook profile enabled)**
  - Counter increments at `postToolUse`
  - At 5 tool calls, hook injects reminder context
  - If still stale, `preToolUse` denies further tools until semantic checkpoint is written

### Resuming a Previous Session

The AI assistant automatically searches for related sessions when starting a new task. To trigger manually:

> "Search openCodeMemory for the Redis caching work from last week"

---

## Removing openCodeMemory

`ocm uninstall` removes openCodeMemory's hooks and rules from your IDE config without touching your session data.

**What is removed:**
- Hook entries from `.claude/settings.json` / `~/.claude/settings.json` (only entries whose command contains `ocm-hook` — other hooks are untouched)
- The `<!-- BEGIN openCodeMemory -->` ... `<!-- END openCodeMemory -->` block from `CLAUDE.md` and `.cursorrules`
- The `opencodememory` key from `.cursor/mcp.json` / `~/.cursor/mcp.json`
- `.cursor/rules/ocm-checkpoint.mdc` — only when its `ocm-version` matches the installed version; user-modified copies are left in place

**What is NOT removed:**
- `.openCodeMemory/` (sessions, DB) — delete manually if desired
- `~/.openCodeMemory/` (global sessions, DB, registry) — delete manually if desired

```bash
ocm uninstall               # project-local config (run from inside the project)
ocm uninstall --global      # global (~/.claude, ~/.cursor) config
```

---

## Data Storage

Storage location depends on setup mode:

- **Project mode (`ocm init`)**: data is local to the project
- **Global mode (`ocm install`)**: data is shared in `~/.openCodeMemory/`

Project mode:

```
<project>/.openCodeMemory/
├── memory.db          # SQLite: metadata + FTS5 index (rebuild-only cache)
├── sessions/*.md      # Markdown files — canonical source of truth
└── active_<id>.jsonl  # Temporary file-edit journals (flushed on checkpoint)
```

Global mode:

```
~/.openCodeMemory/
├── memory.db          # Global SQLite DB used when project DB is absent
├── sessions/*.md      # Global markdown sessions
└── registry.json      # Paths to project DBs (used by global search)
```

**Markdown is the source of truth.** If `memory.db` is deleted or corrupted, run `ocm rebuild-index` to restore the search index from the markdown files.

---

## Contributing

- Bug reports and feature requests via GitHub Issues
- PRs welcome: fork → branch → test → PR
- Run `uv run pytest` before submitting
- **No LLM calls** from within the tool — all intelligence comes from the calling assistant
- **No external network calls** — 100% local, all data stays in `.openCodeMemory/`
- **No ORM** — use stdlib `sqlite3` directly
- Follow existing code style; discuss new dependencies in an issue before adding them
