@lmaksym/agent-mem 0.1.0

package/.claude/commands/context.md

@@ -0,0 +1,24 @@
+# Manage Project Context
+
+Use agent-mem CLI to manage your project's persistent memory.
+
+## Arguments
+$ARGUMENTS: `snapshot | commit <msg> | remember --<category> <text> | lesson "<problem> -> <resolution>" | branch <name> | search <query> | compact [--dry-run|--hard] | resolve [--dry-run] | diff <branch> | forget <path>`
+
+## Instructions
+
+1. If no arguments or "snapshot": run `agent-mem snapshot` and present the context tree
+2. If "commit": run `agent-mem commit <message>`  
+3. If "remember": run `agent-mem remember --<category> "<text>"`
+3b. If "lesson": run `agent-mem lesson "<problem> -> <resolution>"` or with flags `--problem`, `--resolution`, `--tags`
+4. If "branch": run `agent-mem branch <name> "<purpose>"`
+5. If "search": run `agent-mem search "<query>"`
+6. If "compact": run `agent-mem compact [flags]` — archive stale context, keep pins + recent
+7. If "resolve": run `agent-mem resolve [flags]` — auto-resolve merge conflicts in .context/
+8. If "diff": run `agent-mem diff <branch>` — compare branch with main
+9. If "forget": run `agent-mem forget <path>` — remove memory file (archived first)
+10. For any other command, pass directly: `agent-mem <args>`
+
+If `.context/` doesn't exist, run `agent-mem init` first.
+
+Always show the command output to the user.

package/.claude/skills/agent-mem/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: agent-mem
+description: Persistent, git-backed memory across sessions. Use at session start (snapshot), after decisions/fixes/mistakes (remember/lesson), to checkpoint work (commit), before risky exploration (branch), or to check prior context (search).
+argument-hint: "[command] [args] — e.g., snapshot, remember --decision <text>, lesson \"problem -> fix\", commit <msg>"
+---
+
+# agent-mem
+
+Git-backed memory for coding sessions via the `amem` CLI.
+
+If `$ARGUMENTS` is provided, run `agent-mem $ARGUMENTS` and show output.
+
+## When to Use (triggers)
+
+**Starting a session →** `amem snapshot`
+Load context tree, pinned files, memory summary. Run `amem init` if no `.context/` exists.
+
+**You chose between alternatives →** `amem remember --decision "chose X because Y"`
+
+**You noticed a repeatable approach →** `amem remember --pattern "always do X before Y"`
+
+**You did something wrong →** `amem remember --mistake "never do X"`
+
+**You solved a problem after investigation →** `amem lesson "problem -> how you fixed it"`
+Use the `->` shorthand, or `--problem`/`--resolution`/`--tags` flags for richer entries.
+
+**You completed meaningful work →** `amem commit "what you did"`
+
+**You're about to try something that might not work →** `amem branch name "purpose"`
+Merge back with findings: `amem merge name "outcome"`. Even failed branches are valuable.
+
+**You're about to make a decision that might have prior context →** `amem search "query"`
+
+**Session is long, you've learned a lot →** `amem reflect`
+Synthesizes patterns, lessons, stale entries from recent activity.
+
+## Quick Reference
+
+```bash
+amem snapshot                          # start of session
+amem remember --decision "text"        # decision / --pattern / --mistake / --note
+amem lesson "problem -> resolution"    # problem you solved
+amem commit "message"                  # checkpoint progress
+amem branch name "purpose"             # explore uncertain idea
+amem merge name "outcome"              # merge back findings
+amem search "query"                    # check prior context
+amem read <path>                       # read specific file
+amem write <path> --content "text"     # write specific file
+amem pin <path> / amem unpin <path>    # manage pinned files (system/)
+amem reflect                           # gather reflection input
+amem compact [--dry-run|--hard]        # archive stale context
+amem status / amem config / amem help  # info commands
+```
+
+## Remember vs Lesson
+
+**Remember** = one-liner facts: decisions, patterns, mistakes, notes.
+**Lesson** = problem + resolution pair. If you investigated and fixed something, it's a lesson.
+
+## References
+
+- [Reflection & compaction](references/reflection-compaction.md)
+- [Branching & merging](references/branching-merging.md)
+- [Sub-agent patterns](references/sub-agent-patterns.md)
+- [Collaboration & sharing](references/collaboration.md)
+- [Coexistence with CLAUDE.md](references/coexistence.md)

package/.claude/skills/agent-mem/references/branching-merging.md

@@ -0,0 +1,34 @@
+# Branching, Merging & Cleanup
+
+## Diff — compare before merging
+
+Compare a branch's context against main before merging:
+```bash
+amem diff try-qdrant              # summary view
+amem diff try-qdrant --verbose    # show actual line changes
+```
+
+## Resolve — auto-resolve merge conflicts
+
+After git operations that create merge conflicts in `.context/`:
+```bash
+amem resolve --dry-run   # Preview resolution strategy per file
+amem resolve             # Auto-resolve all conflicts
+```
+
+**Resolution strategies (automatic):**
+- `memory/` files — append-only merge (keep both sides, deduplicate exact matches)
+- `config.yaml` — prefer-ours (keep local settings)
+- Other files — keep-both (concatenate with separator)
+
+## Forget — remove obsolete memory
+
+Remove obsolete memory files (archived first for safety):
+```bash
+amem forget memory/old-notes.md
+```
+
+**Safety rules:**
+- Cannot forget pinned `system/` files — run `amem unpin` first
+- Cannot forget `config.yaml`
+- Always archives to `archive/forgotten-YYYY-MM-DD/` before deleting

package/.claude/skills/agent-mem/references/coexistence.md

@@ -0,0 +1,19 @@
+# Coexistence with CLAUDE.md
+
+If the project has a CLAUDE.md:
+- `agent-mem init --from-claude` imports it into `memory/imported-claude-md.md`
+- `.context/system/` becomes the living version of project conventions
+- CLAUDE.md can reference `.context/` for dynamic context
+- Both can coexist — CLAUDE.md for agent instructions, `.context/` for versioned memory
+
+## Syncing to IDE rule files
+
+Export `.context/` content to IDE rule files:
+```bash
+amem sync --claude    # CLAUDE.md
+amem sync --codex     # AGENTS.md
+amem sync --cursor    # .cursorrules
+amem sync --windsurf  # .windsurfrules
+amem sync --gemini    # GEMINI.md
+amem sync --all       # all of the above
+```

package/.claude/skills/agent-mem/references/collaboration.md

@@ -0,0 +1,33 @@
+# Collaboration & Sharing
+
+## Track — git tracking control
+
+Toggle whether `.context/` is tracked in the project's git repo:
+```bash
+amem track              # show current tracking status
+amem track --enable     # add .context/ to project git
+amem track --disable    # remove .context/ from project git
+```
+
+## Push / Pull — remote sync
+
+Sync `.context/` to a separate remote (independent of project git):
+```bash
+amem push                      # push to configured remote
+amem push --remote <url>       # push to specific remote
+amem pull                      # pull from configured remote
+amem pull --remote <url>       # clone/pull from specific remote
+```
+
+## Share / Import — portable snapshots
+
+Generate a portable snapshot of your context for sharing with teammates or other agents:
+```bash
+amem share                     # generate snapshot file
+amem share --output path.json  # custom output path
+```
+
+Import a shared snapshot:
+```bash
+amem import <file>             # import shared snapshot into .context/
+```

package/.claude/skills/agent-mem/references/reflection-compaction.md

@@ -0,0 +1,104 @@
+# Reflection & Compaction
+
+## When to Reflect
+
+Reflection synthesizes what you've learned across multiple commits into structured insights.
+
+**Always reflect:**
+- After completing a multi-step feature (5+ commits)
+- Before ending a long session
+- When you notice you keep re-discovering the same things
+
+**Consider reflecting:**
+- After merging an exploration branch
+- After a debugging session that taught you something
+- When switching between very different problem domains
+
+### The Reflect Cycle
+
+```bash
+# Step 1: Gather context (CLI reads git history + memory state)
+amem reflect
+
+# Step 2: Think about:
+#   - What patterns emerged?
+#   - Do any memories contradict each other?
+#   - What knowledge is missing? What's outdated?
+
+# Step 3: Save your reflection with structured output
+amem reflect save --content "## Patterns Identified
+- WebSocket reconnection needs state validation
+
+## Decisions Validated
+- PKCE for mobile OAuth confirmed as correct
+
+## Contradictions Found
+- Earlier said REST-only, now using WebSocket for streaming. Resolution: REST for CRUD, WS for real-time.
+
+## Stale Entries
+- memory/patterns.md: Use REST for all API endpoints
+
+## Gaps Filled
+- type: pattern
+  text: Always validate WebSocket readiness state, not just connection status
+- type: decision
+  text: REST for CRUD operations, WebSocket for streaming
+
+## Themes
+- Real-time architecture is the dominant concern
+
+## Summary
+Focused on real-time reliability. Key insight: connection != readiness."
+```
+
+### Reflection Output Format
+
+Include these sections (omit empty ones):
+- `## Patterns Identified` — recurring approaches that work
+- `## Lessons Learned` — problems solved: use `type: lesson`, `text:`, `problem:`, `resolution:` fields
+- `## Decisions Validated` — earlier decisions confirmed by recent work
+- `## Contradictions Found` — memory entries that conflict (include resolution)
+- `## Stale Entries` — entries to flag as outdated (format: `file: entry text`)
+- `## Gaps Filled` — new entries to add (use `type:` and `text:` sub-fields)
+- `## Themes` — overarching directions
+- `## Summary` — 2-3 sentences
+
+### Reflection History
+
+```bash
+amem reflect history          # See past reflections + recurring themes
+amem reflect history --last 3 # Last 3 only
+```
+
+### Memory Defrag
+
+When memory files get large or stale:
+```bash
+amem reflect defrag --dry-run  # Analyze memory health (read-only)
+amem reflect defrag            # Apply stale markers (non-destructive)
+# Then clean up manually
+amem write memory/patterns.md "<cleaned content>"
+amem commit "defrag: consolidated patterns"
+```
+
+## When to Compact
+
+Compact when your context is bloated and you want to continue with less noise.
+
+```bash
+amem compact --dry-run   # Preview what would be archived
+amem compact             # Default: archive stale entries, keep pins + last 7 days
+amem compact --hard      # Keep only pinned files, archive everything else
+```
+
+**Use compact when:**
+- Context window is filling up mid-task
+- You want lower noise without losing critical decisions
+- Switching focus within the same session
+
+**Compact always:**
+- Auto-commits before running (safety net)
+- Archives to `.context/archive/compact-YYYY-MM-DD/` (never deletes)
+- Reports byte size before/after
+
+**Compact vs Reflect:** Compact is a pruner (removes noise). Reflect is a synthesizer (extracts insights). Different tools, clean separation.

package/.claude/skills/agent-mem/references/sub-agent-patterns.md

@@ -0,0 +1,60 @@
+# Sub-Agent Patterns
+
+## Spawn Template
+
+Embed amem calls as workflow steps (not a separate block). Agents skip separate instruction blocks but follow numbered steps.
+
+```
+STEP 1: Run amem snapshot — read the output, this is your starting context.
+STEP 2: [First item of actual work]. Then run: amem remember --note "<what you found>"
+STEP 3: [Next item]. Then run: amem remember --note "<what you found>"
+...continue pattern: do work → save finding...
+STEP N (every 3 items): Run amem commit "checkpoint: items 1-3 done"
+FINAL STEP: Write output file, then run: amem commit "done: <summary>"
+```
+
+**Key principle:** Interleave amem into the task flow. Make `remember` the step right after each research item, not a separate section the agent can skip.
+
+## Retry/Resume Template
+
+For sub-agents retrying a timed-out task:
+
+```
+STEP 1: Run amem snapshot — review what the previous run saved.
+STEP 2: Run amem read memory/notes.md — these are completed items, skip them.
+STEP 3: Continue from the first item NOT in notes.md.
+```
+
+## Splitting Large Tasks
+
+Never spawn one agent for 15+ sequential operations. Split instead:
+
+**Bad:** 1 agent x 20 items x (search + fetch + analyze) = timeout
+
+**Good:** 4 agents x 5 items each = parallel, each checkpoints independently
+
+```bash
+# Each sub-agent gets its own branch:
+amem branch batch-1 "items 1-5"
+amem branch batch-2 "items 6-10"
+
+# After all complete, merge branches:
+amem merge batch-1 "findings from items 1-5"
+amem merge batch-2 "findings from items 6-10"
+amem commit "consolidated all research"
+```
+
+## Timeout Recommendations
+
+| Task type | Recommended timeout |
+|-----------|-------------------|
+| Simple (1-3 tool calls) | 120-300s |
+| Research (5-10 searches) | 600s |
+| Deep research (10+ searches) | 900s |
+| Code review | 600s |
+| Browser automation | 300-600s |
+
+## Model Selection for Sub-Agents
+
+- **Sonnet/Haiku** for research tasks — faster, cheaper, less likely to timeout
+- **Opus** for complex reasoning, code architecture decisions

package/LICENSE

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

package/README.md

@@ -0,0 +1,235 @@
+# agent-mem
+
+[![npm version](https://img.shields.io/npm/v/@lmaksym/agent-mem)](https://www.npmjs.com/package/@lmaksym/agent-mem)
+[![CI](https://github.com/lmaksym/agent-context/actions/workflows/ci.yml/badge.svg)](https://github.com/lmaksym/agent-context/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Persistent, git-backed memory for AI coding agents.
+
+> **Alpha** — functional and evolving. Feedback welcome.
+
+## The Problem
+
+AI coding agents lose context between sessions. `CLAUDE.md` is manual. Memory files get stale. Every new session, you re-teach the agent your project conventions, past decisions, and what you already tried.
+
+**agent-mem** gives agents a structured, versioned context filesystem they can read and write through bash. It works with Claude Code, Codex CLI, Cursor, Windsurf, Gemini CLI — any agent that can run shell commands.
+
+On `init`, the skill is automatically installed to the three [Agent Skills](https://agentskills.io) directories (`.claude/skills/`, `.agents/skills/`, `.github/skills/`), covering Claude Code, Codex CLI, Copilot, Gemini CLI, and more. It also auto-syncs trigger-based instructions to detected IDE rule files (CLAUDE.md, GEMINI.md, AGENTS.md, `.cursor/rules/`, `.windsurfrules`).
+
+## Install
+
+```bash
+npm install -g @lmaksym/agent-mem
+```
+
+Requires Node.js 20+. Zero runtime dependencies.
+
+## Quick Start
+
+```bash
+agent-mem init        # Bootstrap from codebase
+agent-mem snapshot    # Agent's primary context view
+```
+
+### Example `snapshot` output
+
+```
+CONTEXT SNAPSHOT
+Project: my-app | Branch: main | Commits: 12
+Last commit: "refactored WebRTC signaling" (2h ago)
+
+PINNED (system/) — always in agent context:
+  --- system/project.md ---
+  # my-app
+  Real-time AI interview platform using Gemini Live.
+  ## Stack
+  Next.js 15, TypeScript, Gemini 2.5, WebRTC, GCP
+
+  --- system/conventions.md ---
+  # Conventions
+  - Domain-driven folder structure
+  - Server components by default
+
+MEMORY (3 files):
+  decisions.md — "12 entries, last: Chose Payload CMS over Directus"
+  patterns.md — "8 patterns, last: Always check Grafana before fixing"
+  mistakes.md — "3 entries, last: Never skip code review"
+
+BRANCHES (1):
+  try-qdrant — "evaluate vector search vs Pinecone" (3 commits)
+
+CONFIG: auto_commit=false | reflection=manual
+```
+
+Pinned files are loaded in full. Everything else is a summary — drill down with `agent-mem read <path>`.
+
+## How Agents Use It
+
+```bash
+# 1. Start session — understand current state
+agent-mem snapshot
+agent-mem read memory/decisions.md
+
+# 2. Do work...
+
+# 3. Record decisions, patterns, mistakes
+agent-mem remember --decision "Chose PKCE over implicit grant for mobile OAuth"
+agent-mem remember --pattern "Always validate WebSocket reconnection with heartbeat"
+agent-mem remember --mistake "Don't use dynamic imports for server components"
+
+# 4. Record lessons learned
+agent-mem lesson "WebSocket reconnect -> validate readiness state, not just connection"
+
+# 5. Checkpoint progress
+agent-mem commit "implemented OAuth PKCE flow"
+
+# 6. Explore something uncertain
+agent-mem branch try-qdrant "evaluate Qdrant vs Pinecone"
+# ... experiment ...
+agent-mem merge try-qdrant "Qdrant wins — self-hosted, better filtering"
+
+# 7. Next session — everything is still there
+agent-mem snapshot
+```
+
+## Commands
+
+### Core
+
+```bash
+agent-mem init [--from-claude]    # Bootstrap .context/ + install skill + sync IDE rules
+agent-mem snapshot                # Context tree with pinned content
+agent-mem read <path>             # Read a specific context file
+agent-mem write <path> --content "text"  # Write a context file (also reads stdin)
+agent-mem commit [message]        # Git-backed checkpoint
+agent-mem status                  # Quick status overview
+```
+
+`--from-claude` imports your existing `CLAUDE.md` into `.context/memory/` so past conventions are preserved.
+
+### Memory
+
+```bash
+agent-mem remember --decision "chose X because Y"   # -> memory/decisions.md
+agent-mem remember --pattern "always do X before Y"  # -> memory/patterns.md
+agent-mem remember --mistake "never do X"            # -> memory/mistakes.md
+agent-mem remember --note "general observation"      # -> memory/notes.md
+agent-mem lesson "API 429 -> implement backoff"      # -> memory/lessons.md
+agent-mem lesson "fix" --problem "OOM" --resolution "close DB conns" --tags "infra"
+agent-mem search <query>          # Grep across all context files
+agent-mem pin <path>              # Move to system/ (always in context)
+agent-mem unpin <path>            # Move out of system/
+```
+
+### Branches
+
+```bash
+agent-mem branch <name> [purpose] # Create exploration branch
+agent-mem switch <name>           # Switch active branch
+agent-mem merge <name> [summary]  # Merge findings back to main
+agent-mem branches                # List all branches
+```
+
+### Compaction & Maintenance
+
+```bash
+agent-mem compact                 # Archive stale entries, keep pins + recent
+agent-mem compact --dry-run       # Preview what would be archived
+agent-mem compact --hard          # Keep only pins, archive everything else
+agent-mem forget <path>           # Remove memory file (archived, never deleted)
+agent-mem resolve                 # Auto-resolve .context/ merge conflicts
+agent-mem resolve --dry-run       # Preview resolution strategy
+agent-mem diff <branch>           # Compare branch context with main
+```
+
+### Reflection
+
+```bash
+agent-mem reflect                 # Gather reflection input
+agent-mem reflect save --content "..."  # Save structured reflection
+agent-mem reflect history         # Past reflections and themes
+agent-mem reflect defrag          # Analyze memory health
+```
+
+### Sync & Sharing
+
+```bash
+agent-mem sync                    # Export to IDE rule files (auto-detect)
+agent-mem sync --claude           # Export to CLAUDE.md
+agent-mem sync --codex            # Export to AGENTS.md
+agent-mem sync --cursor           # Export to .cursor/rules/
+agent-mem sync --windsurf         # Export to .windsurfrules
+agent-mem sync --gemini           # Export to GEMINI.md
+agent-mem sync --all              # Export to all formats
+agent-mem track                   # Toggle .context/ in project git
+agent-mem push                    # Push .context/ to remote
+agent-mem pull                    # Pull .context/ from remote
+agent-mem share                   # Generate portable snapshot
+agent-mem import <file>           # Import shared snapshot
+```
+
+### Config
+
+```bash
+agent-mem config                  # Show current config
+agent-mem config set <key> <val>  # Update config
+```
+
+## Directory Structure
+
+`agent-mem init` creates a `.context/` directory in your project:
+
+```
+.context/
+├── main.md              # Project roadmap and goals
+├── config.yaml          # Settings
+├── system/              # Always loaded into agent context (pinned)
+│   ├── project.md       # Auto-detected: name, stack, structure
+│   └── conventions.md   # Coding conventions and style rules
+├── memory/              # Learned context (tree visible, content on demand)
+│   ├── decisions.md     # Architectural decisions with rationale
+│   ├── patterns.md      # Learned best practices
+│   ├── mistakes.md      # Anti-patterns to avoid
+│   └── lessons.md       # Lessons learned (problem/resolution pairs)
+├── branches/            # Exploration branches with purpose tracking
+├── reflections/         # Reflection outputs and synthesis
+└── archive/             # Archived context from compact/forget (never deleted)
+```
+
+Every change is git-versioned inside `.context/`. Human-readable markdown, diffable, shareable.
+
+## Aliases
+
+```bash
+agent-mem snapshot
+amem snapshot             # short alias
+```
+
+## Design Principles
+
+- **CLI-first** — bash commands, works in any IDE and agent
+- **Agent-native output** — structured text optimized for LLMs
+- **Zero config** — `init` and go
+- **Git-backed** — every change versioned and diffable
+- **Progressive disclosure** — tree shows structure, drill down for details
+- **Zero dependencies** — Node.js built-ins only
+
+## Roadmap
+
+- **Multi-agent coordination** — git worktrees for concurrent agent sessions
+- **Semantic search** — vector-based retrieval across context
+- **Automated reflection** — triggered by commit thresholds
+
+## Inspired By
+
+- [GCC](https://arxiv.org/abs/2508.00031) — Git-inspired COMMIT/BRANCH/MERGE for context management
+- [Letta Context Repos](https://www.letta.com/blog/context-repositories) — Git-backed memory filesystem
+- [Anthropic Context Engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) — Progressive disclosure patterns
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+
+[MIT](LICENSE)