devmemory 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- devmemory/__init__.py +2 -0
- devmemory/cli.py +99 -0
- devmemory/commands/__init__.py +1 -0
- devmemory/commands/add.py +160 -0
- devmemory/commands/config_cmd.py +44 -0
- devmemory/commands/context.py +285 -0
- devmemory/commands/install.py +200 -0
- devmemory/commands/learn.py +216 -0
- devmemory/commands/search.py +245 -0
- devmemory/commands/status.py +71 -0
- devmemory/commands/sync.py +125 -0
- devmemory/core/__init__.py +1 -0
- devmemory/core/ams_client.py +113 -0
- devmemory/core/config.py +42 -0
- devmemory/core/git_ai_parser.py +362 -0
- devmemory/core/llm_client.py +119 -0
- devmemory/core/memory_formatter.py +445 -0
- devmemory/core/sync_state.py +41 -0
- devmemory/hooks/__init__.py +1 -0
- devmemory/hooks/post_commit.py +6 -0
- devmemory/rules/devmemory-context.mdc +16 -0
- devmemory/rules/devmemory.mdc +203 -0
- devmemory-0.1.0.dist-info/METADATA +383 -0
- devmemory-0.1.0.dist-info/RECORD +27 -0
- devmemory-0.1.0.dist-info/WHEEL +4 -0
- devmemory-0.1.0.dist-info/entry_points.txt +2 -0
- devmemory-0.1.0.dist-info/licenses/LICENSE +22 -0
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: DevMemory agent coordination — shared persistent memory across sessions and agents
|
|
3
|
+
alwaysApply: true
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# DevMemory: Shared Agent Memory
|
|
7
|
+
|
|
8
|
+
You have access to a shared project memory via the `agent-memory` MCP server.
|
|
9
|
+
This memory persists across all sessions and is shared between every agent working on this project.
|
|
10
|
+
Use it as a **knowledgebase** (look up past decisions) and **coordination tool** (leave context for future sessions).
|
|
11
|
+
|
|
12
|
+
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.
|
|
13
|
+
|
|
14
|
+
## 1. Before Starting Any Task
|
|
15
|
+
|
|
16
|
+
**Always search memory first.** Before writing code, look up what's already known:
|
|
17
|
+
|
|
18
|
+
```
|
|
19
|
+
search_long_term_memory(text="<describe what you're about to work on>")
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Search for:
|
|
23
|
+
- Past decisions related to your task
|
|
24
|
+
- Known issues or gotchas in the area you're touching
|
|
25
|
+
- Established patterns and conventions
|
|
26
|
+
- Previous attempts that failed and why
|
|
27
|
+
|
|
28
|
+
If your task involves a specific file or module, also search for it:
|
|
29
|
+
```
|
|
30
|
+
search_long_term_memory(text="<module or file name> issues and patterns")
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Also **read the relevant knowledge files** before starting:
|
|
34
|
+
- `.devmemory/knowledge/architecture.md` — architecture decisions and design rationale
|
|
35
|
+
- `.devmemory/knowledge/gotchas.md` — known issues, workarounds, and pitfalls
|
|
36
|
+
- Any other `.md` files in `.devmemory/knowledge/` relevant to your task
|
|
37
|
+
|
|
38
|
+
Incorporate any relevant context into your approach. If a previous session already tried and rejected an approach, don't repeat it.
|
|
39
|
+
|
|
40
|
+
## 2. After Making Significant Decisions
|
|
41
|
+
|
|
42
|
+
You have two ways to persist knowledge, use the right one:
|
|
43
|
+
|
|
44
|
+
### Quick capture: `devmemory add` (CLI)
|
|
45
|
+
|
|
46
|
+
For a single discovery or decision during a session, run:
|
|
47
|
+
```bash
|
|
48
|
+
devmemory add "<what you learned>" --topic <topic> --entity <entity>
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Use this for:
|
|
52
|
+
- A gotcha you just hit and solved
|
|
53
|
+
- An API quirk you discovered mid-task
|
|
54
|
+
- A quick decision that doesn't need a full write-up
|
|
55
|
+
|
|
56
|
+
### Structured knowledge: update `.devmemory/knowledge/` files
|
|
57
|
+
|
|
58
|
+
For anything that future agents should know about, **update the knowledge files directly** and then sync:
|
|
59
|
+
|
|
60
|
+
**When to update knowledge files:**
|
|
61
|
+
- You made an architecture decision (add to `architecture.md`)
|
|
62
|
+
- You discovered a gotcha or workaround (add to `gotchas.md`)
|
|
63
|
+
- You established a new convention or pattern (add to `conventions.md` — create if needed)
|
|
64
|
+
- You added/changed a major dependency and why
|
|
65
|
+
- You fixed a non-obvious bug that could regress
|
|
66
|
+
|
|
67
|
+
**How to update:**
|
|
68
|
+
1. Edit the appropriate `.devmemory/knowledge/*.md` file (or create a new one)
|
|
69
|
+
2. Add a new `## Section Heading` with the content
|
|
70
|
+
3. Run `devmemory learn` to sync the updated files into the memory store
|
|
71
|
+
|
|
72
|
+
**Format for knowledge files:**
|
|
73
|
+
```markdown
|
|
74
|
+
---
|
|
75
|
+
topics: [architecture, decisions]
|
|
76
|
+
entities: [Redis, AMS]
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## Section Title
|
|
80
|
+
Content explaining what, why, and any relevant details.
|
|
81
|
+
Each ## section becomes a separate searchable memory.
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
**If no existing file fits, create a new one.** Good filenames:
|
|
85
|
+
- `architecture.md` — why we chose X over Y, system design
|
|
86
|
+
- `gotchas.md` — things that break if you're not careful
|
|
87
|
+
- `conventions.md` — coding patterns and project rules
|
|
88
|
+
- `api-notes.md` — external API quirks and limitations
|
|
89
|
+
- `dependencies.md` — why we use specific libraries
|
|
90
|
+
|
|
91
|
+
### Also store via MCP for immediate availability
|
|
92
|
+
|
|
93
|
+
After updating knowledge files, also store via MCP so the memory is searchable immediately (before the next `devmemory learn` run):
|
|
94
|
+
|
|
95
|
+
```
|
|
96
|
+
create_long_term_memories(memories=[{
|
|
97
|
+
"text": "<what was decided and why>",
|
|
98
|
+
"memory_type": "semantic",
|
|
99
|
+
"topics": ["<relevant>", "<topics>"],
|
|
100
|
+
"entities": ["<technologies>", "<modules>"]
|
|
101
|
+
}])
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
### What to store as memories
|
|
105
|
+
|
|
106
|
+
| Store | Don't store |
|
|
107
|
+
|-------|-------------|
|
|
108
|
+
| Architecture decisions with rationale | Implementation details obvious from code |
|
|
109
|
+
| Known gotchas and workarounds | Temporary debugging notes |
|
|
110
|
+
| Bug root causes and how they were fixed | Things that change every commit |
|
|
111
|
+
| Project conventions and patterns | Redundant copies of commit messages |
|
|
112
|
+
| API quirks and limitations discovered | Personal preferences |
|
|
113
|
+
| Why approach A was chosen over B | Simple variable renames or formatting |
|
|
114
|
+
|
|
115
|
+
## 3. Keeping Knowledge Files Fresh
|
|
116
|
+
|
|
117
|
+
**This is a core responsibility.** Treat `.devmemory/knowledge/` files like living documentation.
|
|
118
|
+
|
|
119
|
+
### During every session, ask yourself:
|
|
120
|
+
|
|
121
|
+
1. **Did I discover something non-obvious?** → Add to `gotchas.md`
|
|
122
|
+
2. **Did I make a design choice between alternatives?** → Add to `architecture.md`
|
|
123
|
+
3. **Did I establish or follow a pattern?** → Add to `conventions.md` (create if missing)
|
|
124
|
+
4. **Is any existing knowledge file outdated?** → Update it
|
|
125
|
+
|
|
126
|
+
### After updating knowledge files:
|
|
127
|
+
|
|
128
|
+
Always run the sync to push changes into the memory store:
|
|
129
|
+
```bash
|
|
130
|
+
devmemory learn
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### Periodic review
|
|
134
|
+
|
|
135
|
+
If the session involved significant work (new features, refactors, bug fixes), review the knowledge files before finishing:
|
|
136
|
+
- Read through `.devmemory/knowledge/` files you touched or that relate to your work
|
|
137
|
+
- Update anything that's now wrong or incomplete
|
|
138
|
+
- Add sections for new knowledge gained during the session
|
|
139
|
+
- Run `devmemory learn` to sync
|
|
140
|
+
|
|
141
|
+
## 4. Memory Types
|
|
142
|
+
|
|
143
|
+
Use **`semantic`** for timeless facts and decisions:
|
|
144
|
+
- Project conventions, architecture choices, API quirks
|
|
145
|
+
- These answer "how do we do X?" and "why did we choose Y?"
|
|
146
|
+
|
|
147
|
+
Use **`episodic`** for time-bound events (include `event_date`):
|
|
148
|
+
- Migrations, incidents, major refactors
|
|
149
|
+
- These answer "what happened?" and "when did we change X?"
|
|
150
|
+
|
|
151
|
+
## 5. Session Coordination
|
|
152
|
+
|
|
153
|
+
Use working memory to coordinate across active sessions:
|
|
154
|
+
|
|
155
|
+
**At session start** — check if another session left context:
|
|
156
|
+
```
|
|
157
|
+
get_working_memory(session_id="project-coordination")
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
**When starting a large task** — announce what you're working on:
|
|
161
|
+
```
|
|
162
|
+
set_working_memory(
|
|
163
|
+
session_id="project-coordination",
|
|
164
|
+
memories=[{
|
|
165
|
+
"text": "Currently refactoring the search command to add LLM synthesis",
|
|
166
|
+
"memory_type": "semantic",
|
|
167
|
+
"topics": ["active-work"]
|
|
168
|
+
}]
|
|
169
|
+
)
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
**When finishing** — clear or update the coordination state.
|
|
173
|
+
|
|
174
|
+
## 6. Search Before You Reinvent
|
|
175
|
+
|
|
176
|
+
If you're about to:
|
|
177
|
+
- Add a new dependency → search if there's a reason we use something else
|
|
178
|
+
- Change an API pattern → search for conventions
|
|
179
|
+
- Fix a bug → search if it was fixed before and regressed
|
|
180
|
+
- Refactor a module → search for known issues and design decisions
|
|
181
|
+
|
|
182
|
+
The 30 seconds spent searching can save hours of rediscovering what a previous session already learned.
|
|
183
|
+
|
|
184
|
+
## 7. Summary: The Knowledge Loop
|
|
185
|
+
|
|
186
|
+
```
|
|
187
|
+
Session Start
|
|
188
|
+
├─ Run: devmemory context (generates .devmemory/CONTEXT.md briefing)
|
|
189
|
+
├─ Read .devmemory/CONTEXT.md for pre-built context
|
|
190
|
+
├─ search_long_term_memory(text="<your task>") for deeper dives
|
|
191
|
+
├─ Read relevant .devmemory/knowledge/*.md files
|
|
192
|
+
└─ get_working_memory(session_id="project-coordination")
|
|
193
|
+
|
|
194
|
+
During Work
|
|
195
|
+
├─ Hit a gotcha? → devmemory add "..." or update gotchas.md
|
|
196
|
+
├─ Made a decision? → update architecture.md
|
|
197
|
+
└─ Established a pattern? → update conventions.md
|
|
198
|
+
|
|
199
|
+
Session End
|
|
200
|
+
├─ Review and update .devmemory/knowledge/ files
|
|
201
|
+
├─ devmemory learn (sync knowledge files to memory store)
|
|
202
|
+
└─ Update working memory coordination state
|
|
203
|
+
```
|
|
@@ -0,0 +1,383 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: devmemory
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Sync AI coding context from Git AI to Redis Agent Memory Server for semantic search and recall.
|
|
5
|
+
Project-URL: Homepage, https://github.com/devmemory/devmemory
|
|
6
|
+
Project-URL: Repository, https://github.com/devmemory/devmemory
|
|
7
|
+
Author: DevMemory
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: ai,developer-tools,git,mcp,memory,redis
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Environment :: Console
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Topic :: Software Development :: Version Control :: Git
|
|
21
|
+
Requires-Python: >=3.10
|
|
22
|
+
Requires-Dist: httpx>=0.27.0
|
|
23
|
+
Requires-Dist: rich>=13.0.0
|
|
24
|
+
Requires-Dist: typer>=0.12.0
|
|
25
|
+
Provides-Extra: dev
|
|
26
|
+
Requires-Dist: build>=1.2.2; extra == 'dev'
|
|
27
|
+
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
|
|
28
|
+
Requires-Dist: pytest>=8.0.0; extra == 'dev'
|
|
29
|
+
Requires-Dist: ruff>=0.6.0; extra == 'dev'
|
|
30
|
+
Requires-Dist: twine>=5.0.0; extra == 'dev'
|
|
31
|
+
Description-Content-Type: text/markdown
|
|
32
|
+
|
|
33
|
+
# DevMemory 🚀🧠
|
|
34
|
+
|
|
35
|
+
[](https://github.com/devmemory/devmemory/actions/workflows/ci.yml)
|
|
36
|
+
[](https://pypi.org/project/devmemory/)
|
|
37
|
+
[](LICENSE)
|
|
38
|
+
|
|
39
|
+
> **TL;DR**: DevMemory is a long‑term memory for your AI coding agents.
|
|
40
|
+
> It remembers *why* code was written, *how* it changed, and *what* your team learned — then feeds that back into your agents. No more “reinvent the bug” speedruns. 🐛🔥
|
|
41
|
+
|
|
42
|
+
Built on [Git AI](https://usegitai.com/) for silent capture and [Redis Agent Memory Server](https://github.com/redis/agent-memory-server) for semantic search and recall.
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## 💡 What DevMemory Does (in human terms)
|
|
47
|
+
|
|
48
|
+
- 🪝 **Hooks into your git workflow** via Git AI notes
|
|
49
|
+
- 🧬 **Extracts rich memories**:
|
|
50
|
+
- Commit summaries (who, what, why, which agent/model, how much AI)
|
|
51
|
+
- Per‑file code snippets
|
|
52
|
+
- Prompt‑level context with acceptance metrics
|
|
53
|
+
- 🧠 **Stores everything in Redis AMS** as semantic vectors
|
|
54
|
+
- 🔍 **Lets you ask**:
|
|
55
|
+
*“How do we handle auth?”* → it searches, then LLM‑synthesizes an actual answer with sources
|
|
56
|
+
- 🧾 **Ships a knowledge protocol**: `.devmemory/knowledge/*.md` + CLI + Cursor rules so humans and agents keep the docs alive together
|
|
57
|
+
|
|
58
|
+
If Entire saves *how* agents worked and Git AI tracks *who wrote which line*, DevMemory is the part that answers *“Okay, but what did we actually learn?”*.
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## 🧮 How It Works
|
|
63
|
+
|
|
64
|
+
```text
|
|
65
|
+
Developer commits code
|
|
66
|
+
│
|
|
67
|
+
▼
|
|
68
|
+
Git AI captures AI attribution, prompts, agent/model info
|
|
69
|
+
│
|
|
70
|
+
▼
|
|
71
|
+
DevMemory syncs enriched memories to Redis AMS (automatic via post-commit hook)
|
|
72
|
+
│
|
|
73
|
+
├─► Semantic search via CLI (with LLM-synthesized answers)
|
|
74
|
+
├─► MCP recall in Cursor IDE (agents search memory before coding)
|
|
75
|
+
└─► Context briefing auto-generated on branch switch
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
**The knowledge loop:**
|
|
79
|
+
|
|
80
|
+
1. **Capture** – Git AI silently records AI code attribution, prompts, and agent/model info on every commit
|
|
81
|
+
2. **Enrich** – DevMemory extracts three layers per commit: enriched summary, per‑file code snapshots, and prompt‑level context with acceptance metrics
|
|
82
|
+
3. **Search** – Semantic vector search with LLM‑powered answer synthesis (RAG over your git history)
|
|
83
|
+
4. **Recall** – Cursor agents read memory via MCP before writing code, and persist new decisions after
|
|
84
|
+
5. **Learn** – Human‑curated knowledge files (`.devmemory/knowledge/*.md`) feed the same store, capturing architecture decisions and gotchas
|
|
85
|
+
|
|
86
|
+
> 🧵 Think of it as `git log` + “what we should have written in the ADR” + your AI agents actually reading it.
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## 🎥 Demo (what it *feels* like)
|
|
91
|
+
|
|
92
|
+
Imagine:
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
devmemory status # ✅ Stack + hooks look good
|
|
96
|
+
git commit -am "feat: add user auth" # You used an AI agent heavily
|
|
97
|
+
|
|
98
|
+
devmemory sync --latest # Ingest that commit into memory
|
|
99
|
+
devmemory search "how do we handle auth in this service?"
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
You get:
|
|
103
|
+
|
|
104
|
+
- A concise answer synthesized by the LLM (RAG), describing:
|
|
105
|
+
- Which files implement auth
|
|
106
|
+
- Which agent/model was used
|
|
107
|
+
- Key decisions (e.g., why JWT vs sessions)
|
|
108
|
+
- A **Sources** table listing:
|
|
109
|
+
- Commit summaries
|
|
110
|
+
- Relevant per‑file code snippets
|
|
111
|
+
- The original prompts that drove the changes
|
|
112
|
+
|
|
113
|
+
> Drop in a GIF: `docs/demo.gif` — terminal recording of `status → commit → sync → search`.
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## 🚀 Quick Start
|
|
118
|
+
|
|
119
|
+
### Prerequisites
|
|
120
|
+
|
|
121
|
+
- Git
|
|
122
|
+
- Docker + Docker Compose
|
|
123
|
+
- Python 3.10+
|
|
124
|
+
- OpenAI API key (for embeddings and answer synthesis)
|
|
125
|
+
- [Git AI](https://usegitai.com/) (for AI code attribution capture)
|
|
126
|
+
|
|
127
|
+
### One‑Line Setup
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
bash scripts/install.sh
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
This script:
|
|
134
|
+
|
|
135
|
+
- Checks Docker / Python / Git AI
|
|
136
|
+
- Sets up `.env` from `.env.example`
|
|
137
|
+
- Starts Redis + AMS + MCP via Docker
|
|
138
|
+
- Installs the `devmemory` CLI
|
|
139
|
+
- Configures git hooks + Cursor MCP + agent rules in the current repo
|
|
140
|
+
|
|
141
|
+
### Manual Setup
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
git clone https://github.com/devmemory/devmemory
|
|
145
|
+
cd devmemory
|
|
146
|
+
|
|
147
|
+
# Set up environment
|
|
148
|
+
cp .env.example .env
|
|
149
|
+
# Edit .env and add your OPENAI_API_KEY
|
|
150
|
+
|
|
151
|
+
# Start the stack
|
|
152
|
+
make up
|
|
153
|
+
|
|
154
|
+
# Install the CLI
|
|
155
|
+
pip install -e .
|
|
156
|
+
|
|
157
|
+
# Set up hooks, MCP config, and Cursor rules in your project
|
|
158
|
+
cd /path/to/your/project
|
|
159
|
+
devmemory install
|
|
160
|
+
|
|
161
|
+
# Check everything works
|
|
162
|
+
devmemory status
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## ⌨️ CLI Commands
|
|
168
|
+
|
|
169
|
+
### Core workflow 🧠
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
devmemory sync # Sync unsynced Git AI commits to Redis
|
|
173
|
+
devmemory sync --latest # Sync only the latest commit
|
|
174
|
+
devmemory sync --all # Re-sync all commits
|
|
175
|
+
devmemory sync --dry-run # Preview what would be synced
|
|
176
|
+
devmemory search "how do we auth" # Semantic search with LLM-synthesized answer
|
|
177
|
+
devmemory search "auth" -n 5 # Limit results
|
|
178
|
+
devmemory search "auth" --raw # Raw results without LLM synthesis
|
|
179
|
+
devmemory status # Show system health, sync state, hooks
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
### Knowledge management 📚
|
|
183
|
+
|
|
184
|
+
```bash
|
|
185
|
+
devmemory add "We chose Redis over Postgres for vector search because..." --topic architecture
|
|
186
|
+
devmemory add --interactive # Interactive mode with prompts
|
|
187
|
+
devmemory learn # Sync .devmemory/knowledge/*.md into memory store
|
|
188
|
+
devmemory learn --dry-run # Preview what would be synced
|
|
189
|
+
devmemory context # Generate .devmemory/CONTEXT.md from git state + memory
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
### Setup and config ⚙️
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
devmemory install # Set up git hooks + Cursor MCP + agent rules
|
|
196
|
+
devmemory install --skip-hook # Skip hook installation
|
|
197
|
+
devmemory install --skip-rule # Skip Cursor agent rules
|
|
198
|
+
devmemory config show # Show current config
|
|
199
|
+
devmemory config set endpoint URL # Change AMS endpoint
|
|
200
|
+
devmemory config reset # Reset to defaults
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
---
|
|
204
|
+
|
|
205
|
+
## 📚 Knowledge Files
|
|
206
|
+
|
|
207
|
+
DevMemory supports human‑curated knowledge in `.devmemory/knowledge/*.md`.
|
|
208
|
+
Each markdown section (`## heading`) becomes a separate searchable memory.
|
|
209
|
+
|
|
210
|
+
```text
|
|
211
|
+
.devmemory/
|
|
212
|
+
├── CONTEXT.md # Auto-generated context briefing (gitignored)
|
|
213
|
+
└── knowledge/
|
|
214
|
+
├── architecture.md # Architecture decisions and rationale
|
|
215
|
+
├── gotchas.md # Known issues and workarounds
|
|
216
|
+
└── conventions.md # Coding patterns and project rules
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
Knowledge files use frontmatter for metadata:
|
|
220
|
+
|
|
221
|
+
```markdown
|
|
222
|
+
---
|
|
223
|
+
topics: [architecture, decisions]
|
|
224
|
+
entities: [Redis, AMS]
|
|
225
|
+
---
|
|
226
|
+
|
|
227
|
+
## Why We Chose Redis
|
|
228
|
+
|
|
229
|
+
We chose Redis with vector search over dedicated vector DBs
|
|
230
|
+
because it's already part of our stack and reduces complexity.
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
Run `devmemory learn` to sync knowledge files into the memory store.
|
|
234
|
+
Both automated capture (Git AI) **and** human knowledge feed the same searchable store.
|
|
235
|
+
|
|
236
|
+
> 🧠 Pro tip: Treat `.devmemory/knowledge/` like living ADRs. Small, focused, and updated often.
|
|
237
|
+
|
|
238
|
+
---
|
|
239
|
+
|
|
240
|
+
## 🤝 Cursor Agent Integration
|
|
241
|
+
|
|
242
|
+
`devmemory install` sets up three things for Cursor:
|
|
243
|
+
|
|
244
|
+
1. **MCP server config** (`~/.cursor/mcp.json`) – Agents can search and write to the memory store via MCP tools (`search_long_term_memory`, `create_long_term_memories`, etc.)
|
|
245
|
+
2. **Agent behavior rules** (`.cursor/rules/devmemory.mdc`) – Instructs agents to search memory before coding, persist decisions after significant work, and maintain knowledge files
|
|
246
|
+
3. **Context rule** (`.cursor/rules/devmemory-context.mdc`) – Agents read `.devmemory/CONTEXT.md` at task start for a pre‑built briefing
|
|
247
|
+
|
|
248
|
+
The result is a **compounding loop**: each agent session makes the next one smarter.
|
|
249
|
+
Your AI stops acting like a goldfish and starts acting like a teammate. 🐠➡️🧑💻
|
|
250
|
+
|
|
251
|
+
---
|
|
252
|
+
|
|
253
|
+
## 🪝 Git Hooks
|
|
254
|
+
|
|
255
|
+
DevMemory installs two git hooks:
|
|
256
|
+
|
|
257
|
+
| Hook | What it does |
|
|
258
|
+
|------|--------------|
|
|
259
|
+
| `post-commit` | Runs `devmemory sync --latest` in background (auto‑syncs after every commit) |
|
|
260
|
+
| `post-checkout` | Runs `devmemory context --quiet` (refreshes context briefing on branch switch) |
|
|
261
|
+
|
|
262
|
+
---
|
|
263
|
+
|
|
264
|
+
## 🏗 Architecture
|
|
265
|
+
|
|
266
|
+
```text
|
|
267
|
+
┌─────────────────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
|
268
|
+
│ Developer Machine │ │ Docker Stack │ │ Cursor IDE │
|
|
269
|
+
│ │ │ │ │ │
|
|
270
|
+
│ Git AI (git hooks) │ │ Redis Stack │ │ MCP Client │
|
|
271
|
+
│ │ │ │ ▲ │ │ │ │
|
|
272
|
+
│ ▼ │ │ │ │ │ ▼ │
|
|
273
|
+
│ Git Notes (refs/ai) │ │ AMS API (:8000) │ │ MCP Server │
|
|
274
|
+
│ │ │ │ ▲ │ │ (:9050) │
|
|
275
|
+
│ ▼ │ │ │ │ │ │
|
|
276
|
+
│ devmemory sync ────────────┼─────┼────┘ │ │ │
|
|
277
|
+
│ │ │ │ │ │
|
|
278
|
+
│ devmemory search ──────────┼─────┼────► AMS Search ──┼─────┼──► LLM synth │
|
|
279
|
+
│ │ │ │ │ │
|
|
280
|
+
│ .devmemory/knowledge/*.md │ │ │ │ Agent rules │
|
|
281
|
+
│ │ │ │ │ │ (.cursor/rules)│
|
|
282
|
+
│ devmemory learn ───────────┼─────┼────┘ │ │ │
|
|
283
|
+
│ │ │ │ │ │
|
|
284
|
+
│ devmemory context ─────────┼─────┼────► .devmemory/CONTEXT.md │
|
|
285
|
+
└─────────────────────────────┘ └──────────────────┘ └─────────────────┘
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
---
|
|
289
|
+
|
|
290
|
+
## 🧾 What Gets Captured
|
|
291
|
+
|
|
292
|
+
DevMemory extracts three memory layers from each Git AI commit:
|
|
293
|
+
|
|
294
|
+
| Layer | Type | What it contains | Answers |
|
|
295
|
+
|----------------|----------|----------------------------------------------------------------------------------|------------------------------------------|
|
|
296
|
+
| Commit summary | semantic | Agent/model, prompts used, AI contribution stats, acceptance metrics, technologies, files | “Which agent was used?”, “How much AI code?” |
|
|
297
|
+
| Per-file code | episodic | Code snippets from diffs with key lines (imports, class/function defs) | “How do we call the API?”, “What client for Redis?” |
|
|
298
|
+
| Prompt context | semantic | Actual prompt text, acceptance rate, affected files | “What prompts were used?”, “What was the developer asking?” |
|
|
299
|
+
|
|
300
|
+
Unique data points captured via Git AI and surfaced by DevMemory:
|
|
301
|
+
- **AI vs human lines** per commit
|
|
302
|
+
- **Acceptance rate** (lines accepted unchanged vs overridden)
|
|
303
|
+
- **Time waiting for AI** per commit
|
|
304
|
+
- **Agent and model** used (Cursor, Copilot, Claude Code, etc.)
|
|
305
|
+
|
|
306
|
+
---
|
|
307
|
+
|
|
308
|
+
## 🐳 Docker Stack
|
|
309
|
+
|
|
310
|
+
The `docker-compose.yml` runs:
|
|
311
|
+
|
|
312
|
+
| Service | Port | Description |
|
|
313
|
+
|---------|------|-------------|
|
|
314
|
+
| redis | 6379 | Redis Stack (vector search, JSON, streams) |
|
|
315
|
+
| api | 8000 | Agent Memory Server REST API |
|
|
316
|
+
| mcp | 9050 | MCP server for Cursor IDE (SSE mode) |
|
|
317
|
+
| redis-insight | 16381 | RedisInsight UI (debug profile only) |
|
|
318
|
+
|
|
319
|
+
```bash
|
|
320
|
+
make up # Start stack
|
|
321
|
+
make down # Stop stack
|
|
322
|
+
make logs # View logs
|
|
323
|
+
make debug # Start with RedisInsight
|
|
324
|
+
make clean # Stop and remove volumes
|
|
325
|
+
make verify # Run verification checks
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
---
|
|
329
|
+
|
|
330
|
+
## 🌍 How DevMemory Fits the Ecosystem
|
|
331
|
+
|
|
332
|
+
| Tool | What it does | Data store |
|
|
333
|
+
|------|-------------|------------|
|
|
334
|
+
| [Git AI](https://usegitai.com/) | Captures AI code attribution and prompts | Git Notes + SQLite |
|
|
335
|
+
| [Entire](https://entire.io/) | Captures agent sessions/checkpoints | Git branch |
|
|
336
|
+
| **DevMemory** | **Turns captured data into searchable, evolving team knowledge** | **Redis AMS** |
|
|
337
|
+
|
|
338
|
+
Git AI and Entire are **capture tools**.
|
|
339
|
+
DevMemory is a **memory and knowledge tool** — it makes captured data searchable via semantic vector search, synthesizes answers with LLM, and feeds context back to AI agents automatically.
|
|
340
|
+
|
|
341
|
+
---
|
|
342
|
+
|
|
343
|
+
## ⚙️ Configuration
|
|
344
|
+
|
|
345
|
+
Config is stored in `~/.devmemory/config.json`:
|
|
346
|
+
|
|
347
|
+
```json
|
|
348
|
+
{
|
|
349
|
+
"ams_endpoint": "http://localhost:8000",
|
|
350
|
+
"mcp_endpoint": "http://localhost:9050",
|
|
351
|
+
"namespace": "default",
|
|
352
|
+
"user_id": ""
|
|
353
|
+
}
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
Environment variables (in `.env`):
|
|
357
|
+
|
|
358
|
+
| Variable | Default | Description |
|
|
359
|
+
|----------|---------|-------------|
|
|
360
|
+
| `OPENAI_API_KEY` | (required) | Used for embeddings and answer synthesis |
|
|
361
|
+
| `GENERATION_MODEL` | `gpt-5-mini` | Model for LLM answer synthesis |
|
|
362
|
+
| `EMBEDDING_MODEL` | `text-embedding-3-small` | Model for vector embeddings |
|
|
363
|
+
|
|
364
|
+
---
|
|
365
|
+
|
|
366
|
+
## 🧑💻 Contributing
|
|
367
|
+
|
|
368
|
+
Contributions, bug reports, and wild feature ideas are very welcome. 💌
|
|
369
|
+
See [`CONTRIBUTING.md`](CONTRIBUTING.md) for details on running the stack, tests, and linting.
|
|
370
|
+
|
|
371
|
+
If you build something cool with DevMemory, please open an issue or PR and show it off. ✨
|
|
372
|
+
|
|
373
|
+
---
|
|
374
|
+
|
|
375
|
+
## ⭐️ Supporting the Project
|
|
376
|
+
|
|
377
|
+
If DevMemory helps you or your team:
|
|
378
|
+
|
|
379
|
+
- Star the repo on GitHub ⭐
|
|
380
|
+
- Tell your AI‑obsessed friends
|
|
381
|
+
- Open issues with real‑world workflows you’d like memory support for
|
|
382
|
+
|
|
383
|
+
Happy shipping — and may your agents never forget another architecture decision again. 🧠📦🚀
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
devmemory/__init__.py,sha256=piBgWzTaWG5YZyKgrd5Z6l5EIKoL2ev-7Elpl507zcc,49
|
|
2
|
+
devmemory/cli.py,sha256=gEiZjqM-UvfVEYkcDujhHjJ2AyXU_23DKnjNZLn3cew,4676
|
|
3
|
+
devmemory/commands/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
|
|
4
|
+
devmemory/commands/add.py,sha256=A1s_xryp4EccBubeAU_6TEG3bSk7kZmlL5vam_tlhc4,4901
|
|
5
|
+
devmemory/commands/config_cmd.py,sha256=9AQf9pjFWlAGQR1WmJmf3CF7gt8VU9dmXn6A4_HnDsA,1152
|
|
6
|
+
devmemory/commands/context.py,sha256=4tLwq-cv6Us8UE5uj9RTlJJZH0S-EklykxoPumiVHbU,9358
|
|
7
|
+
devmemory/commands/install.py,sha256=uy4-ge2-LSqV4YOkijvsus4BJy2UGMKIlS-R6VYAvoM,7166
|
|
8
|
+
devmemory/commands/learn.py,sha256=e2j8-PSSZc-ea1KpYES6639cEq3R_qQuuKgHx0a6LIo,7130
|
|
9
|
+
devmemory/commands/search.py,sha256=vYBTHrCGWAOOEDzKW0zhltdRPQHkJs8t5OpbvhUBj1E,8402
|
|
10
|
+
devmemory/commands/status.py,sha256=dFFZ0YnJ5BEHfe5i_cNB1AR8ThzNwlULrBRQkBV8czI,2797
|
|
11
|
+
devmemory/commands/sync.py,sha256=we1-vQvMNkLa3qBBbTzbWKL8xXYp8v2f9Sn6BZ2EBWo,4232
|
|
12
|
+
devmemory/core/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
|
|
13
|
+
devmemory/core/ams_client.py,sha256=DBpoMmErvmtqGO0vv0jBsz5HLtL0uthBoYyAavdgZWQ,3629
|
|
14
|
+
devmemory/core/config.py,sha256=7nRbVYpKU5asLy8oIROttDj2tg5Cz7e6qD9v0Zmr65k,1292
|
|
15
|
+
devmemory/core/git_ai_parser.py,sha256=MPh30x7phe1r_Eb7tnzi4MmtkMxdGfwZEG3aoGPkiQ4,10762
|
|
16
|
+
devmemory/core/llm_client.py,sha256=8IPfuNz0C8GXbItth8ldK3YQ20cnGITIyZVLRFBRpXs,3902
|
|
17
|
+
devmemory/core/memory_formatter.py,sha256=QDZCEJON8K9ZQCA2mS5iinOtkBn7lJx0vljk1g4PVog,15670
|
|
18
|
+
devmemory/core/sync_state.py,sha256=ytW1ri68Y9WLChOWnNVEPdWHBMIQAWfHSyH9yQzb3CY,1183
|
|
19
|
+
devmemory/hooks/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
|
|
20
|
+
devmemory/hooks/post_commit.py,sha256=Jyq-VQzOzR1SnPabhDym3SonFQo0kTsCxqPwiZ0VVUg,161
|
|
21
|
+
devmemory/rules/devmemory-context.mdc,sha256=jr6V4mC0Wjyg35cIxkF0Me_06hsEpT9g9WBzal2pXT4,634
|
|
22
|
+
devmemory/rules/devmemory.mdc,sha256=XqPLyrobQl8mrg38yZAx5-iGNx5iHS8o3_ikmtS6cTk,7424
|
|
23
|
+
devmemory-0.1.0.dist-info/METADATA,sha256=IWW0NshvyLVQhnopylBopJ_0hcda6uL2xrSvw8OOBYc,15237
|
|
24
|
+
devmemory-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
|
|
25
|
+
devmemory-0.1.0.dist-info/entry_points.txt,sha256=a28PthmYnKgjgPjN0_DJAvPJ_qtnduNmHThSFIHAY18,49
|
|
26
|
+
devmemory-0.1.0.dist-info/licenses/LICENSE,sha256=pxruW6GG91qP6weq4H2_1wrMyqGNheGU8iPVqD25AdI,1067
|
|
27
|
+
devmemory-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 DevMemory
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
22
|
+
|