{"id":51233693,"url":"https://github.com/thechandanbhagat/pmem-agent","last_synced_at":"2026-06-28T18:32:07.655Z","repository":{"id":361890914,"uuid":"1256303954","full_name":"thechandanbhagat/pmem-agent","owner":"thechandanbhagat","description":"Persistent, concurrent-safe project memory for Claude Code agents","archived":false,"fork":false,"pushed_at":"2026-06-01T17:07:50.000Z","size":15,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-01T18:22:56.207Z","etag":null,"topics":["ai-agent","claude","claude-code","cli","concurrent","developer-tools","github-copilot","npm","project-memory","python"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thechandanbhagat.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-01T16:44:43.000Z","updated_at":"2026-06-01T17:11:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/thechandanbhagat/pmem-agent","commit_stats":null,"previous_names":["thechandanbhagat/pmem-agent"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/thechandanbhagat/pmem-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thechandanbhagat%2Fpmem-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thechandanbhagat%2Fpmem-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thechandanbhagat%2Fpmem-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thechandanbhagat%2Fpmem-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thechandanbhagat","download_url":"https://codeload.github.com/thechandanbhagat/pmem-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thechandanbhagat%2Fpmem-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34900367,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","claude","claude-code","cli","concurrent","developer-tools","github-copilot","npm","project-memory","python"],"created_at":"2026-06-28T18:32:07.583Z","updated_at":"2026-06-28T18:32:07.647Z","avatar_url":"https://github.com/thechandanbhagat.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pmem-agent\n\nPersistent, concurrent-safe project memory for [Claude Code](https://claude.ai/code) agents.\n\nStores structured project facts in `.claude/memory/project-memory.json`. Multiple agents can read and write safely — all operations go through an exclusive file lock with stale-lock detection.\n\n## Install\n\n### pip *(recommended — gives you `pmem` as a system command)*\n\n```bash\npip install pmem-agent\npmem setup          # installs the Claude Code subagent to ~/.claude/agents/\n```\n\n### npx *(no install required)*\n\n```bash\nnpx pmem-agent\n```\n\n### curl — Mac / Linux\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/thechandanbhagat/pmem-agent/main/install.sh | bash\n```\n\n### PowerShell — Windows\n\n```powershell\niwr -useb https://raw.githubusercontent.com/thechandanbhagat/pmem-agent/main/install.ps1 | iex\n```\n\n### Clone and run\n\n```bash\ngit clone https://github.com/thechandanbhagat/pmem-agent\ncd pmem-agent\n./install.sh          # Mac/Linux\n./install.ps1         # Windows (PowerShell)\n```\n\n---\n\n## Quick start\n\n```bash\n# 1. Mark your project root (run once)\ncd ~/projects/my-app\npmem init-root\n\n# 2. Write some facts\npmem write project '{\"name\":\"my-app\",\"type\":\"web-app\"}'\npmem merge '{\"tech_stack\":{\"languages\":[\"TypeScript\"],\"frameworks\":[\"React\"]}}'\n\n# 3. Read them back\npmem read\n```\n\n---\n\n## Multi-repo / monorepo\n\nWhen several git repos share a common parent folder, one `init-root` at the\nparent makes all subrepos share the same memory file automatically.\n\n```\nmy-project/\n├── .pmem-root          ← root marker (gitignored)\n├── .claude/\n│   └── memory/\n│       └── project-memory.json   ← shared by ALL subrepos\n├── api/                ← git repo\n├── web/                ← git repo\n└── mobile/             ← git repo\n```\n\n```bash\ncd ~/projects/my-project\npmem init-root            # one-time setup\n\n# Now from any subrepo, pmem always hits the shared file:\ncd ~/projects/my-project/api\npmem write tech_stack '{\"languages\":[\"TypeScript\"]}'\n\ncd ~/projects/my-project/web\npmem read tech_stack      # same data\n```\n\n**Env var override** (useful in CI):\n\n```bash\nexport PMEM_ROOT=/path/to/my-project\npmem read\n```\n\n**Debug which file will be used:**\n\n```bash\npmem root\n# Memory path: /path/to/my-project/.claude/memory/project-memory.json\n# Source:      .pmem-root marker at /path/to/my-project\n```\n\n---\n\n## Memory schema\n\n```json\n{\n  \"project\":      { \"name\": \"\", \"description\": \"\", \"type\": \"\", \"root\": \"\" },\n  \"tech_stack\":   { \"languages\": [], \"frameworks\": [], \"databases\": [], \"tools\": [] },\n  \"architecture\": { \"pattern\": \"\", \"key_decisions\": [] },\n  \"conventions\":  { \"naming\": \"\", \"file_org\": \"\", \"test_pattern\": \"\" },\n  \"repos\":        {},\n  \"current_goals\": [],\n  \"known_issues\":  [],\n  \"_last_updated\": \"\",\n  \"_agents\":       {}\n}\n```\n\n---\n\n## Using in Claude Code\n\nAfter `pmem setup`, a `project-memory` subagent is available in Claude Code.\nSpawn it at the start of any long-running task:\n\n\u003e \"Initialize project memory\" — scans manifests, README, and directory layout,\n\u003e writes structured facts to `.claude/memory/project-memory.json`.\n\n\u003e \"Load project context\" — reads memory and summarises it before you start work.\n\n\u003e \"Remember that we decided to use Postgres instead of SQLite\" — appends to\n\u003e `architecture.key_decisions`.\n\n### Parallel agent coordination\n\nWhen multiple Claude Code agents run in parallel, each registers itself on\nstartup and reads what peers are working on — preventing duplicate work.\nThe `_agents` key in memory is the coordination table; it is automatically\ncleaned up when each agent finishes.\n\n---\n\n## CLI reference\n\n```\npmem setup                       Install Claude Code subagent to ~/.claude/agents/\npmem init-root                   Mark cwd as project root (shared by all subrepos)\npmem root                        Show resolved memory path\n\npmem read [key]                  Print all memory or one top-level key\npmem write \u003ckey\u003e \u003cvalue\u003e         Set key (value: JSON or plain string)\npmem merge \u003cjson\u003e                Deep-merge a JSON object into memory\npmem delete \u003ckey\u003e                Remove a top-level key\npmem reset                       Wipe all memory\n\npmem agent-register \u003cid\u003e \u003ctask\u003e  Register a running agent\npmem agent-update \u003cid\u003e \u003cstatus\u003e  Update agent status\npmem agent-deregister \u003cid\u003e       Unregister agent on completion\n```\n\n---\n\n## How it works\n\n- **Storage**: plain JSON at `.claude/memory/project-memory.json`\n- **Locking**: `O_CREAT|O_EXCL` on a `.lock` sidecar file — atomic on all major\n  filesystems, no dependencies required\n- **Stale locks**: automatically cleared after 30 s so a crashed agent never\n  permanently blocks others\n- **Root discovery**: walks up from cwd looking for `.pmem-root` marker or an\n  existing memory file — works from any depth in a monorepo\n\n---\n\n## Requirements\n\n- Python 3.10+ (stdlib only — no dependencies)\n- Claude Code (for the subagent)\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthechandanbhagat%2Fpmem-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthechandanbhagat%2Fpmem-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthechandanbhagat%2Fpmem-agent/lists"}