Metadata-Version: 2.4
Name: cwmem
Version: 1.0.0
Summary: Repo-native institutional memory CLI for Enterprise Architecture work.
Project-URL: Homepage, https://github.com/ThomasRohde/cwmem
Project-URL: Repository, https://github.com/ThomasRohde/cwmem
Project-URL: Issues, https://github.com/ThomasRohde/cwmem/issues
Author-email: Thomas Klok Rohde <rohde.thomas@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Thomas Klok Rohde
        
        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: cli,enterprise-architecture,knowledge-graph,memory,sqlite
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: model2vec>=0.5.0
Requires-Dist: numpy>=2.1.0
Requires-Dist: orjson>=3.10.0
Requires-Dist: portalocker>=3.1.1
Requires-Dist: pydantic>=2.10.0
Requires-Dist: typer>=0.16.0
Description-Content-Type: text/markdown

# cwmem

[![PyPI version](https://img.shields.io/pypi/v/cwmem)](https://pypi.org/project/cwmem/)
[![Python 3.12+](https://img.shields.io/pypi/pyversions/cwmem)](https://pypi.org/project/cwmem/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

`cwmem` is a repo-native institutional memory CLI for Enterprise Architecture work.

It keeps fast operational state in SQLite, exports deterministic collaboration artifacts under `memory/`, and gives both humans and coding agents a consistent way to capture decisions, events, entities, and graph links inside a repository.

## Who it is for

- **AI coding agents** that need a stable, scriptable memory layer next to the code they change
- **Enterprise architects** who want architecture decisions, milestones, and relationships stored in the repo
- **Platform and delivery teams** who need search, reviewable exports, and a shared institutional memory

## What `cwmem` gives you

- entry CRUD with automatic lifecycle events
- tags, formal events, and entity / edge graph workflows
- lexical, semantic, hybrid, and graph-expanded retrieval
- deterministic `sync export` / `sync import` for checked-in artifacts
- dry-run, idempotency keys, sidecar locking, `plan`, `validate`, `apply`, and `verify`
- a machine-first JSON-envelope CLI with human-readable help and version output

## Installation

With `pip`:

```bash
pip install cwmem
```

With [`uv`](https://docs.astral.sh/uv/):

```bash
uv tool install cwmem
```

Check the installed version:

```bash
cwmem --version
```

## Quick start

### POSIX shells

```bash
# Initialize the repository memory surfaces
cwmem init

# Capture a decision or note
cwmem add --title "Adopt repo-native memory" --type decision \
  "Store architectural context alongside the codebase."

# Or pipe a plain-text body explicitly
printf 'Store architectural context alongside the codebase.' | \
  cwmem add --title "Adopt repo-native memory" --type decision --body-from-stdin

# Search and inspect what you stored
cwmem search "repo-native memory"
cwmem list

# Add structure with entities and graph edges
cwmem entity-add --entity-type system --name "cwmem"
cwmem link mem-000001 ent-000001 --relation references

# Refresh derived state when needed, then export and verify consistency
cwmem build
cwmem sync export
cwmem sync export --check
cwmem verify
```

### PowerShell

```powershell
# Initialize repository memory surfaces
cwmem init

# Capture a decision
cwmem add --title "Adopt repo-native memory" --type decision `
  "Store architectural context alongside the codebase."

# Or pipe a plain-text body explicitly
Get-Content .\note.txt -Raw | `
  cwmem add --title "Imported note" --type note --body-from-stdin

# Read JSON envelopes naturally in PowerShell
cwmem search "repo-native memory" | ConvertFrom-Json

# Refresh derived state when needed, then export and verify
cwmem build
cwmem sync export
cwmem verify
```

Without `--body-from-stdin`, piped stdin is reserved for JSON object input when
`cwmem add` is driven machine-to-machine.

## How `cwmem` fits into a repository

`cwmem` keeps two views of the same memory system:

- **runtime state** in `.cwmem/` for SQLite, indexes, lock files, and generated plans
- **tracked collaboration artifacts** in `memory/` for review, sync, and git history

The main tracked surfaces are:

- `memory/entries/`
- `memory/events/`
- `memory/graph/`
- `memory/taxonomy/`
- `memory/manifests/`

This split gives you fast local operations without giving up reviewable, deterministic files in version control.

## Core workflow

For everyday memory capture:

```bash
cwmem init
cwmem add --title "Architecture decision" --type decision "Capture the rationale."
cwmem event-add --event-type milestone "MVP shipped"
cwmem search "architecture decision"
cwmem related mem-000001
cwmem build
cwmem sync export
cwmem verify
```

After mutations that affect derived search state or tracked artifacts, the common
safe path is `cwmem build`, then `cwmem sync export`, then `cwmem verify`.

For higher-risk workflows that should be reviewed before mutating state:

```bash
cwmem plan sync-import --plan-out .cwmem/plans/import-plan.json
cwmem validate --plan .cwmem/plans/import-plan.json
cwmem apply --plan .cwmem/plans/import-plan.json
cwmem verify
```

## Safety model

Every command writes exactly one JSON envelope to stdout. That makes the CLI easy to automate, inspect, and pipe into other tooling.

Reads are parallel-safe. Mutating commands serialize through `.cwmem/memory.sqlite.lock` and support safety flags such as:

- `--dry-run`
- `--idempotency-key`
- `--wait-lock`
- `--plan-out`

Use `cwmem guide` when you want the machine-readable command catalog, schema information, and workflow contract.

## Command groups

| Command | What it is for |
|---------|-----------------|
| `cwmem guide` | Machine-readable CLI contract and workflow metadata |
| `cwmem init` / `status` | Bootstrap and inspect repository memory surfaces |
| `cwmem add`, `update`, `tag-add`, `event-add`, `entity-add`, `link` | Capture or mutate memory records |
| `cwmem get`, `list`, `search`, `related`, `graph`, `log` | Read, retrieve, search, and traverse memory |
| `cwmem sync export` / `sync import` | Move between SQLite runtime state and checked-in artifacts |
| `cwmem build`, `stats`, `validate`, `plan`, `apply`, `verify` | Rebuild derived data, inspect health, and run safe workflows |

## Deterministic collaboration surface

`cwmem sync export` writes a deterministic `memory/` tree so that:

- pull requests can review memory changes like code changes
- the runtime database can be reconstructed from tracked artifacts
- CI can detect drift with `cwmem sync export --check`

This makes architecture memory auditable rather than hidden in a local database.

## Local quality gate

Run this before opening a PR or cutting a release:

```bash
uv run ruff check src tests
uv run pyright src
uv run pytest --tb=short
uv build
```

## Release automation

- CI workflow: `.github/workflows/ci.yml`
- Publish workflow: `.github/workflows/publish.yml`
- Contributor guide: `CONTRIBUTING.md`
- Agent expectations: `AGENTS.md`

PyPI publishing uses GitHub OIDC Trusted Publisher with the `pypi` environment and publishes automatically on pushes to `master`.

## Repository docs

- `README.md` — product overview and quick start
- `CONTRIBUTING.md` — local development and release checklist
- `AGENTS.md` — agent expectations and workflow conventions

If you want the CLI to explain itself interactively, start with:

```bash
cwmem --help
cwmem guide
```
