projectmem 0.0.1__tar.gz

projectmem-0.0.1/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.0.1
+
+- Initial local MVP scaffold.

projectmem-0.0.1/LICENSE

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

projectmem-0.0.1/PKG-INFO

@@ -0,0 +1,212 @@
+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