Metadata-Version: 2.3
Name: projectmem
Version: 0.0.1
Summary: Project memory for humans and AI tools: capture issues, attempts, fixes, and decisions in readable Markdown and JSONL.
Project-URL: Homepage, https://github.com/riponcm/projectmem
Project-URL: Repository, https://github.com/riponcm/projectmem
Project-URL: Issues, https://github.com/riponcm/projectmem/issues
Author: Ripon Chandra Malo
License: MIT
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Documentation
Requires-Python: >=3.10
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# projectmem

`projectmem` gives your projects a readable memory.

It records the development story that usually disappears between commits:
issues, failed attempts, working fixes, decisions, notes, and the files involved.
The result is a small `.projectmem/` folder that both humans and AI tools can
read without a vendor-specific integration.

Git shows what changed. `projectmem` helps explain what happened, what was
tried, what failed, and why the current solution exists.

## Why It Exists

Project context is expensive to rebuild.

When you return to a codebase after days or weeks, you often need to rediscover
why something was implemented a certain way. AI coding tools have the same
problem: every new session may scan files, infer history, and repeat analysis
that was already done before.

`projectmem` is designed to reduce that repeated work. Instead of asking a
person or an AI assistant to reconstruct the full project story from source
files alone, it keeps a compact, structured memory in Markdown and JSONL.

For AI-assisted development, the intended pattern is simple:

- read `.projectmem/summary.md` first
- open detailed issue files only when needed
- avoid repeating failed approaches that were already recorded
- spend more context window on the current task instead of rediscovering old
  decisions

The exact token savings depend on the project and workflow, but the goal is to
replace repeated broad scans of tens or hundreds of kilobytes with a concise
summary targeted to stay under roughly 20 KB. In practical AI workflows, that
can save a significant percentage of context tokens across repeated sessions,
especially on long-lived projects.

## What It Captures

`projectmem` is intentionally narrow. It is a project logbook for development
knowledge that does not fit cleanly into commits.

It captures:

- issues you are investigating
- hypotheses and attempts
- whether an attempt worked, failed, or partially helped
- final fixes
- architectural or implementation decisions
- notes and gotchas
- file references that matter to the story

It does not replace Git, issue trackers, documentation, code search, or AI
memory systems. It complements them by preserving the reasoning and failed paths
around a project.

## Installation

```bash
pip install projectmem
```

This installs two commands:

```bash
projectmem
pm
```

Both commands run the same CLI. `projectmem` is the canonical command; `pm` is a
short alias for daily use.

## Quick Start

Initialize memory inside a project:

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

Record the story as you work:

```bash
pm log "auth tokens expire after 1h instead of 24h"
pm attempt "bumped JWT_EXPIRY in config.py" --failed
pm attempt "found hardcoded TTL in middleware" --worked
pm fix "changed TOKEN_TTL in auth/middleware.py:42"
pm decision "keep auth middleware stateless so workers can scale horizontally"
pm note "local test suite requires the test database to be running"
```

Read the current project memory:

```bash
pm show
```

Search previous entries:

```bash
pm search token
```

Regenerate the summary from the raw event log:

```bash
pm regenerate
```

## Project Memory Files

`projectmem init` creates:

```text
.projectmem/
├── summary.md
├── events.jsonl
├── issues/
└── config.toml
```

File roles:

- `.projectmem/summary.md` is the compact memory for humans and AI tools.
- `.projectmem/events.jsonl` is the append-only raw event log.
- `.projectmem/issues/` contains per-issue Markdown files for deeper context.
- `.projectmem/config.toml` stores project-specific settings.

By default, `projectmem init` adds `.projectmem/events.jsonl` to `.gitignore`.
The raw log can contain noisy or sensitive working notes. The generated summary,
issue files, and config are the parts most teams may choose to commit.

## Commands

| Command | Purpose |
|---|---|
| `projectmem init` | Create `.projectmem/` in the current project |
| `pm log <text>` | Start a new issue |
| `pm attempt <text> --worked` | Record a successful attempt |
| `pm attempt <text> --failed` | Record a failed attempt |
| `pm attempt <text> --partial` | Record a partially useful attempt |
| `pm fix <text>` | Record the fix for the current issue |
| `pm decision <text>` | Record a project decision |
| `pm note <text>` | Record a free-form note |
| `pm show` | Print `.projectmem/summary.md` |
| `pm search <query>` | Search recorded events |
| `pm regenerate` | Rebuild the summary from `events.jsonl` |

## AI Workflow

Any AI assistant can use `projectmem` without a plugin.

At the start of a session, ask the assistant to read:

```text
.projectmem/summary.md
```

That file is designed to provide the current project story: recent issues,
outcomes, known gotchas, decisions, and key files. If more detail is needed, the
assistant can open the relevant file under `.projectmem/issues/`.

This keeps the memory portable across tools such as Claude Code, Cursor, Codex,
custom agents, and plain terminal workflows. The storage is ordinary Markdown
and JSONL.

## Design Principles

- Local-first: no network calls, no cloud service, no telemetry.
- Human-readable: Markdown and JSONL only.
- AI-tool-agnostic: no dependency on one assistant or editor.
- Append-only raw log: the original event history remains available.
- Compact derived summary: the main AI-readable file stays small.
- Small CLI surface: a few commands focused on daily development memory.

## Development Status

`projectmem` is in early development. Version `0.0.1` is the initial package
release for testing and name reservation. The first stable public workflow will
come after real use across several projects.

## License

MIT
