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.
Files changed (53) hide show
  1. auto_memory-0.1.0/LICENSE +21 -0
  2. auto_memory-0.1.0/PKG-INFO +285 -0
  3. auto_memory-0.1.0/README.md +262 -0
  4. auto_memory-0.1.0/pyproject.toml +35 -0
  5. auto_memory-0.1.0/setup.cfg +4 -0
  6. auto_memory-0.1.0/src/auto_memory.egg-info/PKG-INFO +285 -0
  7. auto_memory-0.1.0/src/auto_memory.egg-info/SOURCES.txt +51 -0
  8. auto_memory-0.1.0/src/auto_memory.egg-info/dependency_links.txt +1 -0
  9. auto_memory-0.1.0/src/auto_memory.egg-info/entry_points.txt +2 -0
  10. auto_memory-0.1.0/src/auto_memory.egg-info/requires.txt +4 -0
  11. auto_memory-0.1.0/src/auto_memory.egg-info/top_level.txt +1 -0
  12. auto_memory-0.1.0/src/session_recall/__init__.py +0 -0
  13. auto_memory-0.1.0/src/session_recall/__main__.py +117 -0
  14. auto_memory-0.1.0/src/session_recall/commands/__init__.py +0 -0
  15. auto_memory-0.1.0/src/session_recall/commands/checkpoints.py +42 -0
  16. auto_memory-0.1.0/src/session_recall/commands/files.py +42 -0
  17. auto_memory-0.1.0/src/session_recall/commands/health.py +38 -0
  18. auto_memory-0.1.0/src/session_recall/commands/list_sessions.py +81 -0
  19. auto_memory-0.1.0/src/session_recall/commands/schema_check_cmd.py +23 -0
  20. auto_memory-0.1.0/src/session_recall/commands/search.py +103 -0
  21. auto_memory-0.1.0/src/session_recall/commands/show_session.py +73 -0
  22. auto_memory-0.1.0/src/session_recall/config.py +18 -0
  23. auto_memory-0.1.0/src/session_recall/db/__init__.py +0 -0
  24. auto_memory-0.1.0/src/session_recall/db/connect.py +35 -0
  25. auto_memory-0.1.0/src/session_recall/db/schema_check.py +24 -0
  26. auto_memory-0.1.0/src/session_recall/health/__init__.py +0 -0
  27. auto_memory-0.1.0/src/session_recall/health/dim_concurrency.py +33 -0
  28. auto_memory-0.1.0/src/session_recall/health/dim_corpus.py +19 -0
  29. auto_memory-0.1.0/src/session_recall/health/dim_disclosure.py +154 -0
  30. auto_memory-0.1.0/src/session_recall/health/dim_e2e.py +30 -0
  31. auto_memory-0.1.0/src/session_recall/health/dim_freshness.py +19 -0
  32. auto_memory-0.1.0/src/session_recall/health/dim_latency.py +26 -0
  33. auto_memory-0.1.0/src/session_recall/health/dim_repo_coverage.py +27 -0
  34. auto_memory-0.1.0/src/session_recall/health/dim_schema.py +25 -0
  35. auto_memory-0.1.0/src/session_recall/health/dim_summary_coverage.py +35 -0
  36. auto_memory-0.1.0/src/session_recall/health/scoring.py +34 -0
  37. auto_memory-0.1.0/src/session_recall/tests/__init__.py +0 -0
  38. auto_memory-0.1.0/src/session_recall/tests/test_connect.py +44 -0
  39. auto_memory-0.1.0/src/session_recall/tests/test_days_filter.py +225 -0
  40. auto_memory-0.1.0/src/session_recall/tests/test_dim_disclosure.py +90 -0
  41. auto_memory-0.1.0/src/session_recall/tests/test_health_scoring.py +60 -0
  42. auto_memory-0.1.0/src/session_recall/tests/test_list_sessions.py +98 -0
  43. auto_memory-0.1.0/src/session_recall/tests/test_parser.py +15 -0
  44. auto_memory-0.1.0/src/session_recall/tests/test_sanitize_terminal.py +45 -0
  45. auto_memory-0.1.0/src/session_recall/tests/test_schema_check.py +75 -0
  46. auto_memory-0.1.0/src/session_recall/tests/test_search_sanitize.py +51 -0
  47. auto_memory-0.1.0/src/session_recall/tests/test_show_session.py +154 -0
  48. auto_memory-0.1.0/src/session_recall/tests/test_telemetry.py +67 -0
  49. auto_memory-0.1.0/src/session_recall/types.py +21 -0
  50. auto_memory-0.1.0/src/session_recall/util/__init__.py +0 -0
  51. auto_memory-0.1.0/src/session_recall/util/detect_repo.py +25 -0
  52. auto_memory-0.1.0/src/session_recall/util/format_output.py +51 -0
  53. 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
+ [![CI](https://github.com/dezgit2025/auto-memory/actions/workflows/test.yml/badge.svg)](https://github.com/dezgit2025/auto-memory/actions/workflows/test.yml)
33
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
34
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org)
35
+ [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](pyproject.toml)
36
+ [![Tests](https://img.shields.io/badge/tests-90%20passed-brightgreen)]()
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
+ [![CI](https://github.com/dezgit2025/auto-memory/actions/workflows/test.yml/badge.svg)](https://github.com/dezgit2025/auto-memory/actions/workflows/test.yml)
10
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
11
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org)
12
+ [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](pyproject.toml)
13
+ [![Tests](https://img.shields.io/badge/tests-90%20passed-brightgreen)]()
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"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+