devmemory 0.1.0__tar.gz

devmemory-0.1.0/.cursor/rules/devmemory-context.mdc

@@ -0,0 +1,16 @@
+---
+description: Auto-generated project context from DevMemory
+alwaysApply: true
+---
+
+# DevMemory Auto-Context
+
+If `.devmemory/CONTEXT.md` exists, **read it at the start of every task**.
+It contains a pre-built briefing with relevant architecture decisions,
+known gotchas, and coordination state for your current work area.
+
+Run `devmemory context` in the terminal to refresh it before starting work.
+
+This file is auto-generated based on the current git branch, changed files,
+and recent commits. It complements — but does not replace — deeper searches
+via `search_long_term_memory()` through MCP when you need specific answers.

devmemory-0.1.0/.cursor/rules/devmemory.mdc

@@ -0,0 +1,203 @@
+---
+description: DevMemory agent coordination — shared persistent memory across sessions and agents
+alwaysApply: true
+---
+
+# DevMemory: Shared Agent Memory
+
+You have access to a shared project memory via the `agent-memory` MCP server.
+This memory persists across all sessions and is shared between every agent working on this project.
+Use it as a **knowledgebase** (look up past decisions) and **coordination tool** (leave context for future sessions).
+
+The project also maintains **knowledge files** in `.devmemory/knowledge/*.md` — these are the canonical source of architecture decisions, conventions, and gotchas. You are responsible for keeping them up to date.
+
+## 1. Before Starting Any Task
+
+**Always search memory first.** Before writing code, look up what's already known:
+
+```
+search_long_term_memory(text="<describe what you're about to work on>")
+```
+
+Search for:
+- Past decisions related to your task
+- Known issues or gotchas in the area you're touching
+- Established patterns and conventions
+- Previous attempts that failed and why
+
+If your task involves a specific file or module, also search for it:
+```
+search_long_term_memory(text="<module or file name> issues and patterns")
+```
+
+Also **read the relevant knowledge files** before starting:
+- `.devmemory/knowledge/architecture.md` — architecture decisions and design rationale
+- `.devmemory/knowledge/gotchas.md` — known issues, workarounds, and pitfalls
+- Any other `.md` files in `.devmemory/knowledge/` relevant to your task
+
+Incorporate any relevant context into your approach. If a previous session already tried and rejected an approach, don't repeat it.
+
+## 2. After Making Significant Decisions
+
+You have two ways to persist knowledge, use the right one:
+
+### Quick capture: `devmemory add` (CLI)
+
+For a single discovery or decision during a session, run:
+```bash
+devmemory add "<what you learned>" --topic <topic> --entity <entity>
+```
+
+Use this for:
+- A gotcha you just hit and solved
+- An API quirk you discovered mid-task
+- A quick decision that doesn't need a full write-up
+
+### Structured knowledge: update `.devmemory/knowledge/` files
+
+For anything that future agents should know about, **update the knowledge files directly** and then sync:
+
+**When to update knowledge files:**
+- You made an architecture decision (add to `architecture.md`)
+- You discovered a gotcha or workaround (add to `gotchas.md`)
+- You established a new convention or pattern (add to `conventions.md` — create if needed)
+- You added/changed a major dependency and why
+- You fixed a non-obvious bug that could regress
+
+**How to update:**
+1. Edit the appropriate `.devmemory/knowledge/*.md` file (or create a new one)
+2. Add a new `## Section Heading` with the content
+3. Run `devmemory learn` to sync the updated files into the memory store
+
+**Format for knowledge files:**
+```markdown
+---
+topics: [architecture, decisions]
+entities: [Redis, AMS]
+---
+
+## Section Title
+Content explaining what, why, and any relevant details.
+Each ## section becomes a separate searchable memory.
+```
+
+**If no existing file fits, create a new one.** Good filenames:
+- `architecture.md` — why we chose X over Y, system design
+- `gotchas.md` — things that break if you're not careful
+- `conventions.md` — coding patterns and project rules
+- `api-notes.md` — external API quirks and limitations
+- `dependencies.md` — why we use specific libraries
+
+### Also store via MCP for immediate availability
+
+After updating knowledge files, also store via MCP so the memory is searchable immediately (before the next `devmemory learn` run):
+
+```
+create_long_term_memories(memories=[{
+    "text": "<what was decided and why>",
+    "memory_type": "semantic",
+    "topics": ["<relevant>", "<topics>"],
+    "entities": ["<technologies>", "<modules>"]
+}])
+```
+
+### What to store as memories
+
+| Store | Don't store |
+|-------|-------------|
+| Architecture decisions with rationale | Implementation details obvious from code |
+| Known gotchas and workarounds | Temporary debugging notes |
+| Bug root causes and how they were fixed | Things that change every commit |
+| Project conventions and patterns | Redundant copies of commit messages |
+| API quirks and limitations discovered | Personal preferences |
+| Why approach A was chosen over B | Simple variable renames or formatting |
+
+## 3. Keeping Knowledge Files Fresh
+
+**This is a core responsibility.** Treat `.devmemory/knowledge/` files like living documentation.
+
+### During every session, ask yourself:
+
+1. **Did I discover something non-obvious?** → Add to `gotchas.md`
+2. **Did I make a design choice between alternatives?** → Add to `architecture.md`
+3. **Did I establish or follow a pattern?** → Add to `conventions.md` (create if missing)
+4. **Is any existing knowledge file outdated?** → Update it
+
+### After updating knowledge files:
+
+Always run the sync to push changes into the memory store:
+```bash
+devmemory learn
+```
+
+### Periodic review
+
+If the session involved significant work (new features, refactors, bug fixes), review the knowledge files before finishing:
+- Read through `.devmemory/knowledge/` files you touched or that relate to your work
+- Update anything that's now wrong or incomplete
+- Add sections for new knowledge gained during the session
+- Run `devmemory learn` to sync
+
+## 4. Memory Types
+
+Use **`semantic`** for timeless facts and decisions:
+- Project conventions, architecture choices, API quirks
+- These answer "how do we do X?" and "why did we choose Y?"
+
+Use **`episodic`** for time-bound events (include `event_date`):
+- Migrations, incidents, major refactors
+- These answer "what happened?" and "when did we change X?"
+
+## 5. Session Coordination
+
+Use working memory to coordinate across active sessions:
+
+**At session start** — check if another session left context:
+```
+get_working_memory(session_id="project-coordination")
+```
+
+**When starting a large task** — announce what you're working on:
+```
+set_working_memory(
+    session_id="project-coordination",
+    memories=[{
+        "text": "Currently refactoring the search command to add LLM synthesis",
+        "memory_type": "semantic",
+        "topics": ["active-work"]
+    }]
+)
+```
+
+**When finishing** — clear or update the coordination state.
+
+## 6. Search Before You Reinvent
+
+If you're about to:
+- Add a new dependency → search if there's a reason we use something else
+- Change an API pattern → search for conventions
+- Fix a bug → search if it was fixed before and regressed
+- Refactor a module → search for known issues and design decisions
+
+The 30 seconds spent searching can save hours of rediscovering what a previous session already learned.
+
+## 7. Summary: The Knowledge Loop
+
+```
+Session Start
+  ├─ Run: devmemory context  (generates .devmemory/CONTEXT.md briefing)
+  ├─ Read .devmemory/CONTEXT.md for pre-built context
+  ├─ search_long_term_memory(text="<your task>") for deeper dives
+  ├─ Read relevant .devmemory/knowledge/*.md files
+  └─ get_working_memory(session_id="project-coordination")
+
+During Work
+  ├─ Hit a gotcha? → devmemory add "..." or update gotchas.md
+  ├─ Made a decision? → update architecture.md
+  └─ Established a pattern? → update conventions.md
+
+Session End
+  ├─ Review and update .devmemory/knowledge/ files
+  ├─ devmemory learn  (sync knowledge files to memory store)
+  └─ Update working memory coordination state
+```

devmemory-0.1.0/.env.example

@@ -0,0 +1,13 @@
+OPENAI_API_KEY=your_openai_api_key_here
+
+# Optional: override default models
+# GENERATION_MODEL=gpt-5-mini
+# EMBEDDING_MODEL=text-embedding-3-small
+
+# Optional: use Anthropic instead of OpenAI for generation
+# ANTHROPIC_API_KEY=your_anthropic_api_key_here
+# GENERATION_MODEL=claude-3-5-haiku-20241022
+
+# Note: OPENAI_API_KEY and GENERATION_MODEL are used by both the Docker
+# services (AMS/MCP) and the CLI search command for answer synthesis.
+# The CLI will auto-detect these from this .env file or environment variables.

devmemory-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev]
+
+      - name: Run tests
+        run: pytest
+

devmemory-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+.env
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+.venv/
+venv/
+*.so
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+redis_data/
+redisinsight_data/
+*.log
+.DS_Store
+.devmemory/CONTEXT.md
+.devmemory/knowledge/*

devmemory-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+## Changelog
+
+### 0.1.0
+
+- Initial public release of DevMemory.
+- Sync AI coding context from Git AI to Redis Agent Memory Server.
+- Three-layer memory formatting (commit summaries, per-file code, prompt-level context).
+- Knowledge files in `.devmemory/knowledge/*.md` with `devmemory learn`.
+- LLM-synthesized answers for `devmemory search`.
+- Git hooks for automatic sync and context generation.
+- Cursor MCP integration and agent rules for shared memory.
+

devmemory-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+## Contributing to DevMemory
+
+### Development setup
+
+- Clone the repository and create a virtualenv.
+- Copy `.env.example` to `.env` and set `OPENAI_API_KEY`.
+- Start the local stack with `make up`.
+- Install the package in editable mode with dev extras:
+
+```bash
+pip install -e .[dev]
+```
+
+### Running tests and linting
+
+- Run tests with:
+
+```bash
+pytest
+```
+
+- Run Ruff linting (optional) with:
+
+```bash
+ruff check .
+```
+
+### Code style and guidelines
+
+- Use type hints throughout new code.
+- Keep dependencies minimal and aligned with existing stack (typer, httpx, rich).
+- Follow the existing command structure:
+  - CLI entry points in `devmemory/cli.py`.
+  - Command implementations in `devmemory/commands/<name>.py` with `run_<name>()`.
+  - Core logic in `devmemory/core/`.
+
+### Proposing changes
+
+- Open an issue describing the problem or feature.
+- For pull requests:
+  - Create a topic branch from `main`.
+  - Add or update tests when changing behavior.
+  - Ensure `pytest` passes locally.
+  - Keep commits focused and descriptive.
+

devmemory-0.1.0/LICENSE

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

devmemory-0.1.0/Makefile

@@ -0,0 +1,28 @@
+.PHONY: up down logs verify debug clean setup build publish
+
+up:
+	docker compose up -d
+
+down:
+	docker compose down
+
+logs:
+	docker compose logs -f
+
+verify:
+	@bash scripts/verify.sh
+
+debug:
+	docker compose --profile debug up -d
+
+clean:
+	docker compose down -v
+
+setup:
+	@bash scripts/install.sh
+
+build:
+	.venv/bin/python -m build
+
+publish:
+	.venv/bin/twine upload dist/*