projectmem 0.0.1

Project memory for humans and AI tools: capture issues, attempts, fixes, and decisions in readable Markdown and JSONL.

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

pip install projectmem

This installs two commands:

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:

cd path/to/your-project
projectmem init

Record the story as you work:

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:

pm show

Search previous entries:

pm search token

Regenerate the summary from the raw event log:

pm regenerate

Project Memory Files

projectmem init creates:

.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:

.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