auto-memory 0.1.0__tar.gz
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.
- auto_memory-0.1.0/LICENSE +21 -0
- auto_memory-0.1.0/PKG-INFO +285 -0
- auto_memory-0.1.0/README.md +262 -0
- auto_memory-0.1.0/pyproject.toml +35 -0
- auto_memory-0.1.0/setup.cfg +4 -0
- auto_memory-0.1.0/src/auto_memory.egg-info/PKG-INFO +285 -0
- auto_memory-0.1.0/src/auto_memory.egg-info/SOURCES.txt +51 -0
- auto_memory-0.1.0/src/auto_memory.egg-info/dependency_links.txt +1 -0
- auto_memory-0.1.0/src/auto_memory.egg-info/entry_points.txt +2 -0
- auto_memory-0.1.0/src/auto_memory.egg-info/requires.txt +4 -0
- auto_memory-0.1.0/src/auto_memory.egg-info/top_level.txt +1 -0
- auto_memory-0.1.0/src/session_recall/__init__.py +0 -0
- auto_memory-0.1.0/src/session_recall/__main__.py +117 -0
- auto_memory-0.1.0/src/session_recall/commands/__init__.py +0 -0
- auto_memory-0.1.0/src/session_recall/commands/checkpoints.py +42 -0
- auto_memory-0.1.0/src/session_recall/commands/files.py +42 -0
- auto_memory-0.1.0/src/session_recall/commands/health.py +38 -0
- auto_memory-0.1.0/src/session_recall/commands/list_sessions.py +81 -0
- auto_memory-0.1.0/src/session_recall/commands/schema_check_cmd.py +23 -0
- auto_memory-0.1.0/src/session_recall/commands/search.py +103 -0
- auto_memory-0.1.0/src/session_recall/commands/show_session.py +73 -0
- auto_memory-0.1.0/src/session_recall/config.py +18 -0
- auto_memory-0.1.0/src/session_recall/db/__init__.py +0 -0
- auto_memory-0.1.0/src/session_recall/db/connect.py +35 -0
- auto_memory-0.1.0/src/session_recall/db/schema_check.py +24 -0
- auto_memory-0.1.0/src/session_recall/health/__init__.py +0 -0
- auto_memory-0.1.0/src/session_recall/health/dim_concurrency.py +33 -0
- auto_memory-0.1.0/src/session_recall/health/dim_corpus.py +19 -0
- auto_memory-0.1.0/src/session_recall/health/dim_disclosure.py +154 -0
- auto_memory-0.1.0/src/session_recall/health/dim_e2e.py +30 -0
- auto_memory-0.1.0/src/session_recall/health/dim_freshness.py +19 -0
- auto_memory-0.1.0/src/session_recall/health/dim_latency.py +26 -0
- auto_memory-0.1.0/src/session_recall/health/dim_repo_coverage.py +27 -0
- auto_memory-0.1.0/src/session_recall/health/dim_schema.py +25 -0
- auto_memory-0.1.0/src/session_recall/health/dim_summary_coverage.py +35 -0
- auto_memory-0.1.0/src/session_recall/health/scoring.py +34 -0
- auto_memory-0.1.0/src/session_recall/tests/__init__.py +0 -0
- auto_memory-0.1.0/src/session_recall/tests/test_connect.py +44 -0
- auto_memory-0.1.0/src/session_recall/tests/test_days_filter.py +225 -0
- auto_memory-0.1.0/src/session_recall/tests/test_dim_disclosure.py +90 -0
- auto_memory-0.1.0/src/session_recall/tests/test_health_scoring.py +60 -0
- auto_memory-0.1.0/src/session_recall/tests/test_list_sessions.py +98 -0
- auto_memory-0.1.0/src/session_recall/tests/test_parser.py +15 -0
- auto_memory-0.1.0/src/session_recall/tests/test_sanitize_terminal.py +45 -0
- auto_memory-0.1.0/src/session_recall/tests/test_schema_check.py +75 -0
- auto_memory-0.1.0/src/session_recall/tests/test_search_sanitize.py +51 -0
- auto_memory-0.1.0/src/session_recall/tests/test_show_session.py +154 -0
- auto_memory-0.1.0/src/session_recall/tests/test_telemetry.py +67 -0
- auto_memory-0.1.0/src/session_recall/types.py +21 -0
- auto_memory-0.1.0/src/session_recall/util/__init__.py +0 -0
- auto_memory-0.1.0/src/session_recall/util/detect_repo.py +25 -0
- auto_memory-0.1.0/src/session_recall/util/format_output.py +51 -0
- auto_memory-0.1.0/src/session_recall/util/telemetry.py +52 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 auto-memory contributors
|
|
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.
|
|
@@ -0,0 +1,285 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: auto-memory
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Your AI coding agent never forgets — progressive session recall for GitHub Copilot CLI
|
|
5
|
+
Author-email: Desi Villanueva <217994822+dezgit2025@users.noreply.github.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/dezgit2025/auto-memory
|
|
8
|
+
Project-URL: Repository, https://github.com/dezgit2025/auto-memory
|
|
9
|
+
Project-URL: Issues, https://github.com/dezgit2025/auto-memory/issues
|
|
10
|
+
Keywords: session,recall,context,memory,cli,copilot
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
14
|
+
Classifier: Environment :: Console
|
|
15
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
16
|
+
Requires-Python: >=3.10
|
|
17
|
+
Description-Content-Type: text/markdown
|
|
18
|
+
License-File: LICENSE
|
|
19
|
+
Provides-Extra: dev
|
|
20
|
+
Requires-Dist: pytest>=8; extra == "dev"
|
|
21
|
+
Requires-Dist: ruff>=0.6; extra == "dev"
|
|
22
|
+
Dynamic: license-file
|
|
23
|
+
|
|
24
|
+
# auto-memory
|
|
25
|
+
|
|
26
|
+
## Your AI coding agent has amnesia. Here's the fix.
|
|
27
|
+
|
|
28
|
+
*~1,900 lines of Python. Zero dependencies. Saves you an hour a day.*
|
|
29
|
+
|
|
30
|
+
> Built by [Desi Villanueva](https://github.com/dezgit2025)
|
|
31
|
+
|
|
32
|
+
[](https://github.com/dezgit2025/auto-memory/actions/workflows/test.yml)
|
|
33
|
+
[](LICENSE)
|
|
34
|
+
[](https://www.python.org)
|
|
35
|
+
[](pyproject.toml)
|
|
36
|
+
[]()
|
|
37
|
+
|
|
38
|
+
**Zero-dependency CLI that turns Copilot CLI's local SQLite into instant recall — no MCP server, no hooks, read-only, schema-checked. ~50 tokens per prompt.**
|
|
39
|
+
|
|
40
|
+
**Works with:** GitHub Copilot CLI
|
|
41
|
+
**Coming soon:** Claude Code · Cursor · Codex
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
### Quickstart
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
git clone https://github.com/dezgit2025/auto-memory.git
|
|
49
|
+
cd auto-memory && ./install.sh
|
|
50
|
+
session-recall health # verify it works
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Point your agent at [`deploy/install.md`](deploy/install.md) and let it cook. 🍳
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## The Problem
|
|
58
|
+
|
|
59
|
+
Every AI coding agent ships with a big number on the box. 200K tokens. Sounds massive. Here's what actually happens:
|
|
60
|
+
|
|
61
|
+
```
|
|
62
|
+
200,000 tokens — context window (theoretical max)
|
|
63
|
+
120,000 tokens — effective limit before context rot kicks in (~60%)
|
|
64
|
+
-65,000 tokens — MCP tools
|
|
65
|
+
-25,000 tokens — instruction files
|
|
66
|
+
=========
|
|
67
|
+
~30,000 tokens — what you ACTUALLY have before quality degrades
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
LLMs don't degrade gracefully — once you cross roughly **60% of the context window**, the model starts losing coherence. The industry calls it "lost in the middle": attention goes to the beginning (instructions) and the end (recent turns), but your actual working context in the middle gets progressively fuzzier.
|
|
71
|
+
|
|
72
|
+
I timed it over a week: **68 minutes per day** lost to re-orientation after compactions and new sessions.
|
|
73
|
+
|
|
74
|
+
> It's a **death spiral of diminishing context** — each compaction leaves the agent slightly dumber, which burns more tokens explaining things, which triggers the next compaction sooner.
|
|
75
|
+
|
|
76
|
+
### The Compaction Tax
|
|
77
|
+
|
|
78
|
+
Every 20–30 turns, the context warning hits and you get two bad choices: ignore it and watch the agent hallucinate, or run `/compact` and watch it lobotomize itself into a tidy two-paragraph summary of a 30-minute investigation. Either way you lose five minutes re-narrating your own project back to the agent like it's a new hire. That's not a workflow — that's a hamster wheel.
|
|
79
|
+
|
|
80
|
+
## The 200x ROI
|
|
81
|
+
|
|
82
|
+
Here's the cost comparison that made me build this:
|
|
83
|
+
|
|
84
|
+
| Operation | Tokens | What you get |
|
|
85
|
+
|-----------|--------|-------------|
|
|
86
|
+
| `grep -r "auth" src/` | ~5,000-10,000 | 500 results, mostly irrelevant |
|
|
87
|
+
| `find . -name "*.py"` | ~2,000 | Every Python file, no context |
|
|
88
|
+
| Agent re-orientation | ~2,000 | You re-explaining yesterday |
|
|
89
|
+
| **`auto-memory files --json --limit 10`** | **~50** | **Exactly the 10 files you touched yesterday** |
|
|
90
|
+
|
|
91
|
+
**50 tokens vs 10,000 — a 200x improvement.**
|
|
92
|
+
|
|
93
|
+
## Before & After
|
|
94
|
+
|
|
95
|
+
**Before auto-memory** — new session on a project:
|
|
96
|
+
|
|
97
|
+
```
|
|
98
|
+
You: Fix the failing test in the auth module
|
|
99
|
+
|
|
100
|
+
Agent: Let me explore the project structure...
|
|
101
|
+
$ find . -name "*.py" | head -50 ← 2K tokens
|
|
102
|
+
$ grep -r "test.*auth" tests/ ← 5K tokens
|
|
103
|
+
$ cat tests/test_auth.py ← 3K tokens
|
|
104
|
+
$ cat src/auth/handler.py ← 2K tokens
|
|
105
|
+
I see several test files. Which test is failing?
|
|
106
|
+
|
|
107
|
+
You: The one we were working on yesterday, the token refresh edge case
|
|
108
|
+
|
|
109
|
+
Agent: Let me search for that...
|
|
110
|
+
$ grep -r "refresh" tests/ ← 4K tokens
|
|
111
|
+
...
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Total: ~16K tokens burned, 8 minutes elapsed, agent still isn't oriented.
|
|
115
|
+
|
|
116
|
+
**After auto-memory** — same scenario:
|
|
117
|
+
|
|
118
|
+
```
|
|
119
|
+
You: Fix the failing test in the auth module
|
|
120
|
+
|
|
121
|
+
Agent: [auto-recall: auto-memory files --json --limit 10]
|
|
122
|
+
→ src/auth/refresh.py, tests/test_refresh_edge_cases.py,
|
|
123
|
+
src/auth/token_store.py (last touched 14h ago)
|
|
124
|
+
|
|
125
|
+
[auto-recall: auto-memory list --json --limit 3]
|
|
126
|
+
→ Yesterday: "Fixed token refresh race condition, one edge case
|
|
127
|
+
test still failing on expired token + network timeout combo"
|
|
128
|
+
|
|
129
|
+
I can see from your last session that test_refresh_edge_cases.py
|
|
130
|
+
has a failing test for the expired token + network timeout case.
|
|
131
|
+
Let me look at that specific test...
|
|
132
|
+
$ cat tests/test_refresh_edge_cases.py ← 1K tokens (targeted)
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Total: ~1.1K tokens, 30 seconds, agent is immediately productive.
|
|
136
|
+
|
|
137
|
+
## How it compares
|
|
138
|
+
|
|
139
|
+
| Approach | Dependencies | Writes to DB | Setup | Agent-native |
|
|
140
|
+
|----------|-------------|-------------|-------|-------------|
|
|
141
|
+
| **auto-memory** | None (stdlib) | ❌ Read-only | `pip install` | ✅ Instruction-file |
|
|
142
|
+
| MCP server | Node.js runtime | Varies | Server config | ❌ Protocol layer |
|
|
143
|
+
| Custom hooks | Varies | Often yes | Hook scripts | ❌ Event-driven |
|
|
144
|
+
| Manual grep | None | ❌ | None | ❌ Manual |
|
|
145
|
+
|
|
146
|
+
## Mental Model: RAM vs Disk
|
|
147
|
+
|
|
148
|
+
- **Context window = RAM.** Fast, limited, clears on restart.
|
|
149
|
+
- **session-store.db = Disk.** Persistent, searchable, grows forever.
|
|
150
|
+
|
|
151
|
+
auto-memory is the **page fault handler** — it pulls exact facts from disk in ~50 tokens when the agent needs them.
|
|
152
|
+
|
|
153
|
+
**It's not unlimited context. It's unlimited context *recall*.** In practice, same thing.
|
|
154
|
+
|
|
155
|
+
## Design
|
|
156
|
+
|
|
157
|
+
```
|
|
158
|
+
┌─────────────────────────────────────────────────┐
|
|
159
|
+
│ copilot-instructions.md │
|
|
160
|
+
│ "Run auto-memory FIRST on every prompt" │
|
|
161
|
+
└──────────────────┬──────────────────────────────┘
|
|
162
|
+
│ agent reads instruction
|
|
163
|
+
▼
|
|
164
|
+
┌─────────────────────────────────────────────────┐
|
|
165
|
+
│ auto-memory CLI │
|
|
166
|
+
│ (pure Python, zero deps, read-only) │
|
|
167
|
+
└──────────────────┬──────────────────────────────┘
|
|
168
|
+
│ SELECT ... FROM sessions
|
|
169
|
+
▼
|
|
170
|
+
┌─────────────────────────────────────────────────┐
|
|
171
|
+
│ ~/.copilot/session-store.db │
|
|
172
|
+
│ (SQLite + FTS5, owned by Copilot CLI binary) │
|
|
173
|
+
└─────────────────────────────────────────────────┘
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
- **Zero dependencies** — stdlib only (sqlite3, json, argparse)
|
|
177
|
+
- **Read-only** — never writes to `~/.copilot/session-store.db`
|
|
178
|
+
- **WAL-safe** — exponential backoff retry on SQLITE_BUSY (50→150→450ms)
|
|
179
|
+
- **Schema-aware** — validates expected schema on every call, fails fast on drift
|
|
180
|
+
- **Telemetry** — ring buffer of last 100 invocations for concurrency monitoring
|
|
181
|
+
|
|
182
|
+
## Usage
|
|
183
|
+
|
|
184
|
+
### Try these prompts with your agent
|
|
185
|
+
|
|
186
|
+
Once wired into your agent's instruction file, session-recall runs on every prompt — giving the agent your recent files and sessions as context before it does anything else.
|
|
187
|
+
|
|
188
|
+
|
|
189
|
+
```
|
|
190
|
+
"Search recent sessions about fixing the db connection bug"
|
|
191
|
+
"Check past 5 days sessions for latest plans?"
|
|
192
|
+
"Pick up where we left off on the API refactor"
|
|
193
|
+
"search recent sessions for last 10 files we modified"
|
|
194
|
+
"search sessions for the db migration bug"
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
No special syntax. The agent reads your session history and gets oriented in seconds instead of minutes.
|
|
198
|
+
|
|
199
|
+
### How it works under the hood
|
|
200
|
+
|
|
201
|
+
Progressive disclosure — most prompts never get past Tier 1.
|
|
202
|
+
|
|
203
|
+
**Tier 1 — Cheap scan (~50 tokens).** Usually enough.
|
|
204
|
+
|
|
205
|
+
```bash
|
|
206
|
+
session-recall files --json --limit 10
|
|
207
|
+
session-recall list --json --limit 5
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
**Tier 2 — Focused recall (~200 tokens).** When Tier 1 isn't enough.
|
|
211
|
+
|
|
212
|
+
```bash
|
|
213
|
+
session-recall search "specific term" --json
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
**Tier 3 — Full session detail (~500 tokens).** Only when investigating something specific.
|
|
217
|
+
|
|
218
|
+
```bash
|
|
219
|
+
session-recall show <session-id> --json
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
**Operational commands:**
|
|
223
|
+
|
|
224
|
+
```bash
|
|
225
|
+
session-recall health # 9-dimension health dashboard
|
|
226
|
+
session-recall schema-check # validate DB schema after Copilot CLI upgrades
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
## Health Check
|
|
230
|
+
|
|
231
|
+
```
|
|
232
|
+
Dim Name Zone Score Detail
|
|
233
|
+
----------------------------------------------------------------------
|
|
234
|
+
1 DB Freshness 🟢 GREEN 8.0 15.8h old
|
|
235
|
+
2 Schema Integrity 🟢 GREEN 10.0 All tables/columns OK
|
|
236
|
+
3 Query Latency 🟢 GREEN 10.0 1ms
|
|
237
|
+
4 Corpus Size 🟢 GREEN 10.0 399 sessions
|
|
238
|
+
5 Summary Coverage 🟢 GREEN 7.4 92% (367/399)
|
|
239
|
+
6 Repo Coverage 🟢 GREEN 10.0 8 sessions for owner/repo
|
|
240
|
+
7 Concurrency 🟢 GREEN 10.0 busy=0.0%, p95=48ms
|
|
241
|
+
8 E2E Probe 🟢 GREEN 10.0 list→show OK
|
|
242
|
+
9 Progressive Disclosure ⚪ CALIBRATING — Collecting baseline (n=42/200)
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
## Agent Integration
|
|
246
|
+
|
|
247
|
+
auto-memory works with **any agent that supports instruction files** — GitHub Copilot CLI, Claude Code, Cursor, Aider, Windsurf, and more. Installation wires session-recall into your agent's instruction file so it runs context recall automatically.
|
|
248
|
+
|
|
249
|
+
See [`deploy/install.md`](deploy/install.md) for setup and [`copilot-instructions-template.md`](copilot-instructions-template.md) for integration patterns.
|
|
250
|
+
|
|
251
|
+
See [`UPGRADE-COPILOT-CLI.md`](UPGRADE-COPILOT-CLI.md) for schema validation after Copilot CLI upgrades.
|
|
252
|
+
|
|
253
|
+
## What This Isn't
|
|
254
|
+
|
|
255
|
+
- **Not a vector database** — no embeddings, SQLite FTS5 only.
|
|
256
|
+
- **Not cross-machine sync** — local only.
|
|
257
|
+
- **Not a replacement for project documentation** — recalls *what you did*, not *how the system works*.
|
|
258
|
+
|
|
259
|
+
## FAQ
|
|
260
|
+
|
|
261
|
+
**Is it safe? Does it modify my session data?**
|
|
262
|
+
No. auto-memory is strictly read-only. It never writes to `~/.copilot/session-store.db`.
|
|
263
|
+
|
|
264
|
+
**What happens when Copilot CLI updates its schema?**
|
|
265
|
+
Run `session-recall schema-check` to validate. The tool fails fast on schema drift rather than returning bad data. See [UPGRADE-COPILOT-CLI.md](UPGRADE-COPILOT-CLI.md).
|
|
266
|
+
|
|
267
|
+
## Roadmap
|
|
268
|
+
|
|
269
|
+
See [ROADMAP.md](ROADMAP.md).
|
|
270
|
+
|
|
271
|
+
## Contributing
|
|
272
|
+
|
|
273
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and guidelines. Issues, PRs, and docs improvements are welcome.
|
|
274
|
+
|
|
275
|
+
⭐ **If auto-memory saved you time, [star the repo](https://github.com/dezgit2025/auto-memory)** — it's the best way to help others find it.
|
|
276
|
+
|
|
277
|
+
🔗 **Share it:** *"Zero-dependency CLI that gives your AI coding agent session memory. Read-only, schema-checked, ~50 tokens per prompt."* → [github.com/dezgit2025/auto-memory](https://github.com/dezgit2025/auto-memory)
|
|
278
|
+
|
|
279
|
+
## Disclaimer
|
|
280
|
+
|
|
281
|
+
This is an independent open-source project. It is **not** affiliated with, endorsed by, or supported by Microsoft, GitHub, or any other company. There is no official support — use at your own risk. Contributions and issues are welcome on GitHub.
|
|
282
|
+
|
|
283
|
+
## License
|
|
284
|
+
|
|
285
|
+
MIT
|
|
@@ -0,0 +1,262 @@
|
|
|
1
|
+
# auto-memory
|
|
2
|
+
|
|
3
|
+
## Your AI coding agent has amnesia. Here's the fix.
|
|
4
|
+
|
|
5
|
+
*~1,900 lines of Python. Zero dependencies. Saves you an hour a day.*
|
|
6
|
+
|
|
7
|
+
> Built by [Desi Villanueva](https://github.com/dezgit2025)
|
|
8
|
+
|
|
9
|
+
[](https://github.com/dezgit2025/auto-memory/actions/workflows/test.yml)
|
|
10
|
+
[](LICENSE)
|
|
11
|
+
[](https://www.python.org)
|
|
12
|
+
[](pyproject.toml)
|
|
13
|
+
[]()
|
|
14
|
+
|
|
15
|
+
**Zero-dependency CLI that turns Copilot CLI's local SQLite into instant recall — no MCP server, no hooks, read-only, schema-checked. ~50 tokens per prompt.**
|
|
16
|
+
|
|
17
|
+
**Works with:** GitHub Copilot CLI
|
|
18
|
+
**Coming soon:** Claude Code · Cursor · Codex
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
### Quickstart
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
git clone https://github.com/dezgit2025/auto-memory.git
|
|
26
|
+
cd auto-memory && ./install.sh
|
|
27
|
+
session-recall health # verify it works
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Point your agent at [`deploy/install.md`](deploy/install.md) and let it cook. 🍳
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## The Problem
|
|
35
|
+
|
|
36
|
+
Every AI coding agent ships with a big number on the box. 200K tokens. Sounds massive. Here's what actually happens:
|
|
37
|
+
|
|
38
|
+
```
|
|
39
|
+
200,000 tokens — context window (theoretical max)
|
|
40
|
+
120,000 tokens — effective limit before context rot kicks in (~60%)
|
|
41
|
+
-65,000 tokens — MCP tools
|
|
42
|
+
-25,000 tokens — instruction files
|
|
43
|
+
=========
|
|
44
|
+
~30,000 tokens — what you ACTUALLY have before quality degrades
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
LLMs don't degrade gracefully — once you cross roughly **60% of the context window**, the model starts losing coherence. The industry calls it "lost in the middle": attention goes to the beginning (instructions) and the end (recent turns), but your actual working context in the middle gets progressively fuzzier.
|
|
48
|
+
|
|
49
|
+
I timed it over a week: **68 minutes per day** lost to re-orientation after compactions and new sessions.
|
|
50
|
+
|
|
51
|
+
> It's a **death spiral of diminishing context** — each compaction leaves the agent slightly dumber, which burns more tokens explaining things, which triggers the next compaction sooner.
|
|
52
|
+
|
|
53
|
+
### The Compaction Tax
|
|
54
|
+
|
|
55
|
+
Every 20–30 turns, the context warning hits and you get two bad choices: ignore it and watch the agent hallucinate, or run `/compact` and watch it lobotomize itself into a tidy two-paragraph summary of a 30-minute investigation. Either way you lose five minutes re-narrating your own project back to the agent like it's a new hire. That's not a workflow — that's a hamster wheel.
|
|
56
|
+
|
|
57
|
+
## The 200x ROI
|
|
58
|
+
|
|
59
|
+
Here's the cost comparison that made me build this:
|
|
60
|
+
|
|
61
|
+
| Operation | Tokens | What you get |
|
|
62
|
+
|-----------|--------|-------------|
|
|
63
|
+
| `grep -r "auth" src/` | ~5,000-10,000 | 500 results, mostly irrelevant |
|
|
64
|
+
| `find . -name "*.py"` | ~2,000 | Every Python file, no context |
|
|
65
|
+
| Agent re-orientation | ~2,000 | You re-explaining yesterday |
|
|
66
|
+
| **`auto-memory files --json --limit 10`** | **~50** | **Exactly the 10 files you touched yesterday** |
|
|
67
|
+
|
|
68
|
+
**50 tokens vs 10,000 — a 200x improvement.**
|
|
69
|
+
|
|
70
|
+
## Before & After
|
|
71
|
+
|
|
72
|
+
**Before auto-memory** — new session on a project:
|
|
73
|
+
|
|
74
|
+
```
|
|
75
|
+
You: Fix the failing test in the auth module
|
|
76
|
+
|
|
77
|
+
Agent: Let me explore the project structure...
|
|
78
|
+
$ find . -name "*.py" | head -50 ← 2K tokens
|
|
79
|
+
$ grep -r "test.*auth" tests/ ← 5K tokens
|
|
80
|
+
$ cat tests/test_auth.py ← 3K tokens
|
|
81
|
+
$ cat src/auth/handler.py ← 2K tokens
|
|
82
|
+
I see several test files. Which test is failing?
|
|
83
|
+
|
|
84
|
+
You: The one we were working on yesterday, the token refresh edge case
|
|
85
|
+
|
|
86
|
+
Agent: Let me search for that...
|
|
87
|
+
$ grep -r "refresh" tests/ ← 4K tokens
|
|
88
|
+
...
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Total: ~16K tokens burned, 8 minutes elapsed, agent still isn't oriented.
|
|
92
|
+
|
|
93
|
+
**After auto-memory** — same scenario:
|
|
94
|
+
|
|
95
|
+
```
|
|
96
|
+
You: Fix the failing test in the auth module
|
|
97
|
+
|
|
98
|
+
Agent: [auto-recall: auto-memory files --json --limit 10]
|
|
99
|
+
→ src/auth/refresh.py, tests/test_refresh_edge_cases.py,
|
|
100
|
+
src/auth/token_store.py (last touched 14h ago)
|
|
101
|
+
|
|
102
|
+
[auto-recall: auto-memory list --json --limit 3]
|
|
103
|
+
→ Yesterday: "Fixed token refresh race condition, one edge case
|
|
104
|
+
test still failing on expired token + network timeout combo"
|
|
105
|
+
|
|
106
|
+
I can see from your last session that test_refresh_edge_cases.py
|
|
107
|
+
has a failing test for the expired token + network timeout case.
|
|
108
|
+
Let me look at that specific test...
|
|
109
|
+
$ cat tests/test_refresh_edge_cases.py ← 1K tokens (targeted)
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Total: ~1.1K tokens, 30 seconds, agent is immediately productive.
|
|
113
|
+
|
|
114
|
+
## How it compares
|
|
115
|
+
|
|
116
|
+
| Approach | Dependencies | Writes to DB | Setup | Agent-native |
|
|
117
|
+
|----------|-------------|-------------|-------|-------------|
|
|
118
|
+
| **auto-memory** | None (stdlib) | ❌ Read-only | `pip install` | ✅ Instruction-file |
|
|
119
|
+
| MCP server | Node.js runtime | Varies | Server config | ❌ Protocol layer |
|
|
120
|
+
| Custom hooks | Varies | Often yes | Hook scripts | ❌ Event-driven |
|
|
121
|
+
| Manual grep | None | ❌ | None | ❌ Manual |
|
|
122
|
+
|
|
123
|
+
## Mental Model: RAM vs Disk
|
|
124
|
+
|
|
125
|
+
- **Context window = RAM.** Fast, limited, clears on restart.
|
|
126
|
+
- **session-store.db = Disk.** Persistent, searchable, grows forever.
|
|
127
|
+
|
|
128
|
+
auto-memory is the **page fault handler** — it pulls exact facts from disk in ~50 tokens when the agent needs them.
|
|
129
|
+
|
|
130
|
+
**It's not unlimited context. It's unlimited context *recall*.** In practice, same thing.
|
|
131
|
+
|
|
132
|
+
## Design
|
|
133
|
+
|
|
134
|
+
```
|
|
135
|
+
┌─────────────────────────────────────────────────┐
|
|
136
|
+
│ copilot-instructions.md │
|
|
137
|
+
│ "Run auto-memory FIRST on every prompt" │
|
|
138
|
+
└──────────────────┬──────────────────────────────┘
|
|
139
|
+
│ agent reads instruction
|
|
140
|
+
▼
|
|
141
|
+
┌─────────────────────────────────────────────────┐
|
|
142
|
+
│ auto-memory CLI │
|
|
143
|
+
│ (pure Python, zero deps, read-only) │
|
|
144
|
+
└──────────────────┬──────────────────────────────┘
|
|
145
|
+
│ SELECT ... FROM sessions
|
|
146
|
+
▼
|
|
147
|
+
┌─────────────────────────────────────────────────┐
|
|
148
|
+
│ ~/.copilot/session-store.db │
|
|
149
|
+
│ (SQLite + FTS5, owned by Copilot CLI binary) │
|
|
150
|
+
└─────────────────────────────────────────────────┘
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
- **Zero dependencies** — stdlib only (sqlite3, json, argparse)
|
|
154
|
+
- **Read-only** — never writes to `~/.copilot/session-store.db`
|
|
155
|
+
- **WAL-safe** — exponential backoff retry on SQLITE_BUSY (50→150→450ms)
|
|
156
|
+
- **Schema-aware** — validates expected schema on every call, fails fast on drift
|
|
157
|
+
- **Telemetry** — ring buffer of last 100 invocations for concurrency monitoring
|
|
158
|
+
|
|
159
|
+
## Usage
|
|
160
|
+
|
|
161
|
+
### Try these prompts with your agent
|
|
162
|
+
|
|
163
|
+
Once wired into your agent's instruction file, session-recall runs on every prompt — giving the agent your recent files and sessions as context before it does anything else.
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
```
|
|
167
|
+
"Search recent sessions about fixing the db connection bug"
|
|
168
|
+
"Check past 5 days sessions for latest plans?"
|
|
169
|
+
"Pick up where we left off on the API refactor"
|
|
170
|
+
"search recent sessions for last 10 files we modified"
|
|
171
|
+
"search sessions for the db migration bug"
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
No special syntax. The agent reads your session history and gets oriented in seconds instead of minutes.
|
|
175
|
+
|
|
176
|
+
### How it works under the hood
|
|
177
|
+
|
|
178
|
+
Progressive disclosure — most prompts never get past Tier 1.
|
|
179
|
+
|
|
180
|
+
**Tier 1 — Cheap scan (~50 tokens).** Usually enough.
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
session-recall files --json --limit 10
|
|
184
|
+
session-recall list --json --limit 5
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
**Tier 2 — Focused recall (~200 tokens).** When Tier 1 isn't enough.
|
|
188
|
+
|
|
189
|
+
```bash
|
|
190
|
+
session-recall search "specific term" --json
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
**Tier 3 — Full session detail (~500 tokens).** Only when investigating something specific.
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
session-recall show <session-id> --json
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
**Operational commands:**
|
|
200
|
+
|
|
201
|
+
```bash
|
|
202
|
+
session-recall health # 9-dimension health dashboard
|
|
203
|
+
session-recall schema-check # validate DB schema after Copilot CLI upgrades
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
## Health Check
|
|
207
|
+
|
|
208
|
+
```
|
|
209
|
+
Dim Name Zone Score Detail
|
|
210
|
+
----------------------------------------------------------------------
|
|
211
|
+
1 DB Freshness 🟢 GREEN 8.0 15.8h old
|
|
212
|
+
2 Schema Integrity 🟢 GREEN 10.0 All tables/columns OK
|
|
213
|
+
3 Query Latency 🟢 GREEN 10.0 1ms
|
|
214
|
+
4 Corpus Size 🟢 GREEN 10.0 399 sessions
|
|
215
|
+
5 Summary Coverage 🟢 GREEN 7.4 92% (367/399)
|
|
216
|
+
6 Repo Coverage 🟢 GREEN 10.0 8 sessions for owner/repo
|
|
217
|
+
7 Concurrency 🟢 GREEN 10.0 busy=0.0%, p95=48ms
|
|
218
|
+
8 E2E Probe 🟢 GREEN 10.0 list→show OK
|
|
219
|
+
9 Progressive Disclosure ⚪ CALIBRATING — Collecting baseline (n=42/200)
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
## Agent Integration
|
|
223
|
+
|
|
224
|
+
auto-memory works with **any agent that supports instruction files** — GitHub Copilot CLI, Claude Code, Cursor, Aider, Windsurf, and more. Installation wires session-recall into your agent's instruction file so it runs context recall automatically.
|
|
225
|
+
|
|
226
|
+
See [`deploy/install.md`](deploy/install.md) for setup and [`copilot-instructions-template.md`](copilot-instructions-template.md) for integration patterns.
|
|
227
|
+
|
|
228
|
+
See [`UPGRADE-COPILOT-CLI.md`](UPGRADE-COPILOT-CLI.md) for schema validation after Copilot CLI upgrades.
|
|
229
|
+
|
|
230
|
+
## What This Isn't
|
|
231
|
+
|
|
232
|
+
- **Not a vector database** — no embeddings, SQLite FTS5 only.
|
|
233
|
+
- **Not cross-machine sync** — local only.
|
|
234
|
+
- **Not a replacement for project documentation** — recalls *what you did*, not *how the system works*.
|
|
235
|
+
|
|
236
|
+
## FAQ
|
|
237
|
+
|
|
238
|
+
**Is it safe? Does it modify my session data?**
|
|
239
|
+
No. auto-memory is strictly read-only. It never writes to `~/.copilot/session-store.db`.
|
|
240
|
+
|
|
241
|
+
**What happens when Copilot CLI updates its schema?**
|
|
242
|
+
Run `session-recall schema-check` to validate. The tool fails fast on schema drift rather than returning bad data. See [UPGRADE-COPILOT-CLI.md](UPGRADE-COPILOT-CLI.md).
|
|
243
|
+
|
|
244
|
+
## Roadmap
|
|
245
|
+
|
|
246
|
+
See [ROADMAP.md](ROADMAP.md).
|
|
247
|
+
|
|
248
|
+
## Contributing
|
|
249
|
+
|
|
250
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and guidelines. Issues, PRs, and docs improvements are welcome.
|
|
251
|
+
|
|
252
|
+
⭐ **If auto-memory saved you time, [star the repo](https://github.com/dezgit2025/auto-memory)** — it's the best way to help others find it.
|
|
253
|
+
|
|
254
|
+
🔗 **Share it:** *"Zero-dependency CLI that gives your AI coding agent session memory. Read-only, schema-checked, ~50 tokens per prompt."* → [github.com/dezgit2025/auto-memory](https://github.com/dezgit2025/auto-memory)
|
|
255
|
+
|
|
256
|
+
## Disclaimer
|
|
257
|
+
|
|
258
|
+
This is an independent open-source project. It is **not** affiliated with, endorsed by, or supported by Microsoft, GitHub, or any other company. There is no official support — use at your own risk. Contributions and issues are welcome on GitHub.
|
|
259
|
+
|
|
260
|
+
## License
|
|
261
|
+
|
|
262
|
+
MIT
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68.0"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "auto-memory"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Your AI coding agent never forgets — progressive session recall for GitHub Copilot CLI"
|
|
9
|
+
requires-python = ">=3.10"
|
|
10
|
+
license = {text = "MIT"}
|
|
11
|
+
authors = [{name = "Desi Villanueva", email = "217994822+dezgit2025@users.noreply.github.com"}]
|
|
12
|
+
readme = "README.md"
|
|
13
|
+
keywords = ["session", "recall", "context", "memory", "cli", "copilot"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 3 - Alpha",
|
|
16
|
+
"Programming Language :: Python :: 3",
|
|
17
|
+
"License :: OSI Approved :: MIT License",
|
|
18
|
+
"Environment :: Console",
|
|
19
|
+
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
20
|
+
]
|
|
21
|
+
dependencies = []
|
|
22
|
+
|
|
23
|
+
[project.scripts]
|
|
24
|
+
session-recall = "session_recall.__main__:main"
|
|
25
|
+
|
|
26
|
+
[project.urls]
|
|
27
|
+
Homepage = "https://github.com/dezgit2025/auto-memory"
|
|
28
|
+
Repository = "https://github.com/dezgit2025/auto-memory"
|
|
29
|
+
Issues = "https://github.com/dezgit2025/auto-memory/issues"
|
|
30
|
+
|
|
31
|
+
[project.optional-dependencies]
|
|
32
|
+
dev = ["pytest>=8", "ruff>=0.6"]
|
|
33
|
+
|
|
34
|
+
[tool.setuptools.packages.find]
|
|
35
|
+
where = ["src"]
|