git-memex 0.3.2__tar.gz → 0.4.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 (44) hide show
  1. {git_memex-0.3.2 → git_memex-0.4.0}/CHANGELOG.md +23 -0
  2. {git_memex-0.3.2/src/git_memex.egg-info → git_memex-0.4.0}/PKG-INFO +62 -33
  3. {git_memex-0.3.2 → git_memex-0.4.0}/README.md +59 -30
  4. {git_memex-0.3.2 → git_memex-0.4.0}/pyproject.toml +4 -2
  5. {git_memex-0.3.2 → git_memex-0.4.0/src/git_memex.egg-info}/PKG-INFO +62 -33
  6. {git_memex-0.3.2 → git_memex-0.4.0}/src/git_memex.egg-info/SOURCES.txt +1 -0
  7. git_memex-0.4.0/src/memex/__init__.py +3 -0
  8. {git_memex-0.3.2 → git_memex-0.4.0}/src/memex/cli.py +55 -14
  9. {git_memex-0.3.2 → git_memex-0.4.0}/src/memex/install.py +9 -5
  10. {git_memex-0.3.2 → git_memex-0.4.0}/src/memex/models.py +3 -0
  11. {git_memex-0.3.2 → git_memex-0.4.0}/src/memex/service.py +24 -3
  12. {git_memex-0.3.2 → git_memex-0.4.0}/src/memex/store.py +71 -9
  13. git_memex-0.4.0/src/memex/templates/AGENTS.md +72 -0
  14. git_memex-0.4.0/src/memex/templates/llms.txt +81 -0
  15. git_memex-0.4.0/src/memex/templates/memex.mdc +17 -0
  16. {git_memex-0.3.2 → git_memex-0.4.0}/src/memex/templates/skills/memex-hygiene/SKILL.md +18 -13
  17. {git_memex-0.3.2 → git_memex-0.4.0}/src/memex/tools.py +14 -9
  18. {git_memex-0.3.2 → git_memex-0.4.0}/src/memex/vectors.py +23 -5
  19. {git_memex-0.3.2 → git_memex-0.4.0}/tests/test_cli.py +47 -1
  20. {git_memex-0.3.2 → git_memex-0.4.0}/tests/test_install.py +41 -13
  21. {git_memex-0.3.2 → git_memex-0.4.0}/tests/test_store.py +40 -0
  22. {git_memex-0.3.2 → git_memex-0.4.0}/tests/test_tools.py +38 -1
  23. {git_memex-0.3.2 → git_memex-0.4.0}/tests/test_vectors.py +36 -0
  24. git_memex-0.3.2/src/memex/__init__.py +0 -3
  25. git_memex-0.3.2/src/memex/templates/AGENTS.md +0 -65
  26. git_memex-0.3.2/src/memex/templates/memex.mdc +0 -15
  27. {git_memex-0.3.2 → git_memex-0.4.0}/LICENSE +0 -0
  28. {git_memex-0.3.2 → git_memex-0.4.0}/MANIFEST.in +0 -0
  29. {git_memex-0.3.2 → git_memex-0.4.0}/examples/claude-mcp.json +0 -0
  30. {git_memex-0.3.2 → git_memex-0.4.0}/examples/codex-config.toml +0 -0
  31. {git_memex-0.3.2 → git_memex-0.4.0}/examples/cursor-mcp.json +0 -0
  32. {git_memex-0.3.2 → git_memex-0.4.0}/setup.cfg +0 -0
  33. {git_memex-0.3.2 → git_memex-0.4.0}/src/git_memex.egg-info/dependency_links.txt +0 -0
  34. {git_memex-0.3.2 → git_memex-0.4.0}/src/git_memex.egg-info/entry_points.txt +0 -0
  35. {git_memex-0.3.2 → git_memex-0.4.0}/src/git_memex.egg-info/requires.txt +0 -0
  36. {git_memex-0.3.2 → git_memex-0.4.0}/src/git_memex.egg-info/top_level.txt +0 -0
  37. {git_memex-0.3.2 → git_memex-0.4.0}/src/memex/__main__.py +0 -0
  38. {git_memex-0.3.2 → git_memex-0.4.0}/src/memex/config.py +0 -0
  39. {git_memex-0.3.2 → git_memex-0.4.0}/src/memex/embedder.py +0 -0
  40. {git_memex-0.3.2 → git_memex-0.4.0}/src/memex/gitroot.py +0 -0
  41. {git_memex-0.3.2 → git_memex-0.4.0}/src/memex/server.py +0 -0
  42. {git_memex-0.3.2 → git_memex-0.4.0}/tests/test_embedder.py +0 -0
  43. {git_memex-0.3.2 → git_memex-0.4.0}/tests/test_gitroot.py +0 -0
  44. {git_memex-0.3.2 → git_memex-0.4.0}/tests/test_merge_reindex.py +0 -0
@@ -2,6 +2,29 @@
2
2
 
3
3
  ## Unreleased
4
4
 
5
+ ## 0.4.0 — 2026-11-10
6
+
7
+ - **CLI-first agent integration.** Agent prompts (`AGENTS.md` block, Cursor
8
+ rule, `memex-hygiene` skill) now tell agents to run the `memex` CLI
9
+ (`memex recall "…"`, `memex remember "…" --tags …`) instead of MCP tools, so
10
+ Memex works in any harness that can run shell commands.
11
+ - New `memex llms` (alias `memex llms.txt`): prints an `llms.txt`-style agent
12
+ guide — workflow, every command and flag, JSON shapes, env vars.
13
+ - `memex remember -` reads the fact from stdin (avoids shell quoting).
14
+ - New install target `agents`: writes only the `AGENTS.md` block + layout, for
15
+ harnesses without dedicated wiring. `all` now includes it.
16
+ - **Breaking:** `memex install` no longer writes MCP config by default; pass
17
+ `--mcp` to write `.cursor/mcp.json` / `.mcp.json` / `.codex/config.toml`.
18
+ `--no-mcp` is still accepted (now a no-op). Existing MCP config is left as is.
19
+ - Fixed a date-dependent recency ranking test that failed once its fixed
20
+ "fresh" timestamp aged past the 30-day half-life.
21
+
22
+ ## 0.3.3 — 2026-09-06
23
+
24
+ - Optional note **`paths`**: durable related scope (repo-relative files/folders)
25
+ on frontmatter and in `memory.db`. Pass via `remember` / `--paths`; returned on
26
+ `recall` and `list`. Not a session changelog; no ranking boost yet.
27
+
5
28
  ## 0.3.2 — 2026-08-21
6
29
 
7
30
  - `recall` adds opt-in recency boosting, `tags_all` AND filtering, and
@@ -1,12 +1,12 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: git-memex
3
- Version: 0.3.2
4
- Summary: Memex: repo-local vector memory — CLI + MCP remember/recall inside the git repository
3
+ Version: 0.4.0
4
+ Summary: Memex: repo-local vector memory for AI agents — CLI-first remember/recall inside the git repository (optional MCP)
5
5
  Author: Daniel
6
6
  License-Expression: MIT
7
7
  Project-URL: Homepage, https://github.com/daniel/memex
8
8
  Project-URL: Repository, https://github.com/daniel/memex
9
- Keywords: mcp,agent-memory,vector-search,sqlite-vec,git
9
+ Keywords: cli,llms-txt,mcp,agent-memory,vector-search,sqlite-vec,git
10
10
  Classifier: Development Status :: 4 - Beta
11
11
  Classifier: Intended Audience :: Developers
12
12
  Classifier: Programming Language :: Python :: 3
@@ -31,7 +31,10 @@ Dynamic: license-file
31
31
 
32
32
  Repo-local vector memory for AI agents. Memories live **inside the git repository**
33
33
  as mergeable markdown notes plus a rebuildable sqlite-vec index. Use the `memex`
34
- CLI or a stdio MCP server to `remember` and `recall` by semantic relevance.
34
+ CLI to `remember` and `recall` by semantic relevance. The CLI is the primary
35
+ interface, so it works in any LLM harness that can run shell commands; agents
36
+ get a full usage guide from `memex llms` (an `llms.txt`). A stdio MCP server
37
+ (`memex serve`) is available as an opt-in extra.
35
38
 
36
39
  Published on PyPI as [`git-memex`](https://pypi.org/project/git-memex/) (`memex` was already taken).
37
40
 
@@ -74,10 +77,11 @@ uv run pytest
74
77
 
75
78
  On Linux/WSL, use `python3` if `python` is not found.
76
79
 
77
- ## Cursor MCP config
80
+ ## Optional MCP config
78
81
 
79
- Prefer **`memex install cursor`** in the target repo — it writes `.cursor/mcp.json`
80
- with a portable home path (after `uv tool install` / `pipx`):
82
+ Agents use the CLI by default. To also register the MCP server, pass `--mcp`:
83
+ **`memex install cursor --mcp`** writes `.cursor/mcp.json` with a portable home
84
+ path (after `uv tool install` / `pipx`):
81
85
 
82
86
  ```json
83
87
  {
@@ -103,15 +107,23 @@ the server walks parents from the process cwd looking for `.git`.
103
107
 
104
108
  ## Claude Desktop / Claude Code
105
109
 
106
- For Claude Code, prefer **`memex install claude`** (writes project `.mcp.json` +
107
- `CLAUDE.md`). Default command is bare `memex` (on PATH). See
108
- `examples/claude-mcp.json`.
110
+ For Claude Code, prefer **`memex install claude`** (writes `CLAUDE.md`; add
111
+ `--mcp` for project `.mcp.json`). Default MCP command is bare `memex` (on PATH).
112
+ See `examples/claude-mcp.json`.
109
113
 
110
114
  ## Codex
111
115
 
112
- Prefer **`memex install codex`**. Default command is bare `memex`; Codex still
116
+ Prefer **`memex install codex`** (writes `AGENTS.md`; add `--mcp` for the
117
+ `.codex/config.toml` block). Default MCP command is bare `memex`; Codex still
113
118
  gets an absolute `MEMEX_ROOT` for the repo. See `examples/codex-config.toml`.
114
119
 
120
+ ## Any other harness
121
+
122
+ **`memex install agents`** writes only the CLI-first Memex block to `AGENTS.md`
123
+ (plus `.memex/` layout and `.gitattributes`). Any agent that reads `AGENTS.md`
124
+ and can run shell commands can then use Memex; point it at `memex llms` for
125
+ the full reference.
126
+
115
127
  ## On-disk layout
116
128
 
117
129
  ```text
@@ -130,16 +142,21 @@ pull that changes notes, the next `recall` auto-reindexes if the DB is stale.
130
142
  ## CLI
131
143
 
132
144
  After install, the `memex` console script is a CLI. Running `memex` with no
133
- arguments prints help. Start the MCP server with `memex serve`.
145
+ arguments prints help. `memex llms` prints the agent guide (`llms.txt`: workflow,
146
+ every command and flag, JSON shapes). Start the optional MCP server with
147
+ `memex serve`.
134
148
 
135
149
  ```bash
136
150
  memex # show help
137
151
  memex help
138
152
  memex help install
139
- memex install cursor # Cursor rule + MCP + .cursor/skills
140
- memex install claude # CLAUDE.md + .mcp.json
141
- memex install codex # AGENTS.md + .codex/config.toml MCP
153
+ memex llms # agent/LLM usage guide (llms.txt)
154
+ memex install agents # AGENTS.md only (any harness)
155
+ memex install cursor # AGENTS.md + Cursor rule + .cursor/skills
156
+ memex install claude # AGENTS.md + CLAUDE.md
157
+ memex install codex # AGENTS.md
142
158
  memex install all
159
+ memex install all --mcp # also write MCP server configs
143
160
  memex status
144
161
  memex list
145
162
  memex list --tags decision --limit 20
@@ -147,12 +164,14 @@ memex list --tags-all auth,decision --offset 20 --limit 20
147
164
  memex reindex # rebuild memory.db from .memex/notes
148
165
  memex reindex --force # rebuild even when fingerprints match
149
166
  memex remember "We use JWT in httpOnly cookies" --tags auth,decision
167
+ memex remember "Auth lives in the cookie middleware" --tags auth,bugfix --paths src/auth/
150
168
  memex remember "Strip locale from JWT" --replaces <uuid>
169
+ echo "Fact with \"quotes\"" | memex remember - --tags convention # read from stdin
151
170
  memex recall "how is auth handled?" -k 5
152
171
  memex recall "how is auth handled?" --tags-all auth,security --recency
153
172
  memex recall "how is auth handled?" --rank blended
154
173
  memex forget <uuid>
155
- memex serve # stdio MCP server
174
+ memex serve # optional stdio MCP server
156
175
  ```
157
176
 
158
177
  Add `--json` to any command for machine-readable output. From a checkout:
@@ -163,13 +182,15 @@ make reindex
163
182
  make reindex FORCE=1
164
183
  ```
165
184
 
166
- ## MCP tools
185
+ ## MCP tools (optional)
186
+
187
+ `memex serve` exposes the same operations as MCP tools:
167
188
 
168
189
  | Tool | Purpose |
169
190
  |------|---------|
170
- | `remember` | Store a memory; skips/updates near-duplicates & elaborations; `replaces` updates by id |
171
- | `recall` | Semantic KNN search; returns untrusted evidence with timestamps |
172
- | `list` | Catalog notes (id, first line, tags, dates) without embeddings |
191
+ | `remember` | Store a memory; skips/updates near-duplicates & elaborations; `replaces` updates by id; optional `paths` for related scope |
192
+ | `recall` | Semantic KNN search; returns untrusted evidence with timestamps and optional `paths` |
193
+ | `list` | Catalog notes (id, first line, tags, paths, dates) without embeddings |
173
194
  | `reindex` | Rebuild `memory.db` from notes |
174
195
  | `forget` | Delete a memory by id |
175
196
  | `status` | Repo root, counts, tag histogram, model, staleness |
@@ -180,6 +201,8 @@ tag; `--tags-all` requires every listed tag. `--recency` applies a bounded
180
201
  freshness boost with a 30-day half-life. `--rank blended` opts into combined
181
202
  semantic, freshness, tag-overlap, and type-tag ranking; cosine remains the
182
203
  default and the returned `score` remains raw cosine similarity.
204
+ Optional `paths` on `remember` (comma-separated repo-relative files/folders) is
205
+ durable related scope for bugfixes and module conventions—not a session diff.
183
206
  When `remember` inserts a new note that is close to an existing one, the response
184
207
  includes `conflicts` and may include advisory `suggested_tags`. Recall hits may
185
208
  include `conflict: true` when multiple near-neighbor notes could represent
@@ -200,11 +223,13 @@ verify important notes against the repository.
200
223
  In any git repository where agents should use Memex, install for your platform(s):
201
224
 
202
225
  ```bash
226
+ memex install agents # AGENTS.md only — any harness
203
227
  memex install cursor
204
228
  memex install claude
205
229
  memex install codex
206
- memex install all # cursor + claude + codex
230
+ memex install all # agents + cursor + claude + codex
207
231
  memex install cursor claude # multiple targets
232
+ memex install all --mcp # also write MCP server configs
208
233
  ```
209
234
 
210
235
  Every target is idempotent and always:
@@ -218,27 +243,31 @@ Platform extras:
218
243
 
219
244
  | Target | Also writes |
220
245
  |--------|-------------|
221
- | `cursor` | short always-on `.cursor/rules/memex.mdc` (points at the `AGENTS.md` Memex block), `.cursor/mcp.json` (`${userHome}/…`, `MEMEX_ROOT=${workspaceFolder}`), `.cursor/skills/` from `templates/skills/` |
222
- | `claude` | `CLAUDE.md`, `.mcp.json` (`command: memex`, `MEMEX_ROOT=${CLAUDE_PROJECT_DIR:-.}`) |
223
- | `codex` | `.codex/config.toml` MCP block (`command: memex`, absolute `MEMEX_ROOT`) |
246
+ | `agents` | nothing else |
247
+ | `cursor` | short always-on `.cursor/rules/memex.mdc` (points at the `AGENTS.md` Memex block), `.cursor/skills/` from `templates/skills/`; with `--mcp`: `.cursor/mcp.json` (`${userHome}/…`, `MEMEX_ROOT=${workspaceFolder}`) |
248
+ | `claude` | `CLAUDE.md`; with `--mcp`: `.mcp.json` (`command: memex`, `MEMEX_ROOT=${CLAUDE_PROJECT_DIR:-.}`) |
249
+ | `codex` | with `--mcp`: `.codex/config.toml` MCP block (`command: memex`, absolute `MEMEX_ROOT`) |
224
250
 
225
251
  Re-run after upgrading `git-memex` to refresh prompts from packaged templates.
226
- Flags: `--no-agents`, `--no-instructions`, `--no-rules`, `--no-mcp`,
227
- `--no-skills`, `--no-gitattributes`, `--command /path/to/memex`.
252
+ Flags: `--mcp`, `--no-agents`, `--no-instructions`, `--no-rules`,
253
+ `--no-skills`, `--no-gitattributes`, `--command /path/to/memex` (MCP binary).
254
+ Re-running without `--mcp` never removes MCP config written earlier.
228
255
 
229
256
  Templates live in the package (`src/memex/templates/`). `AGENTS.md` is the
230
- canonical agent prompt; the Cursor `.mdc` is a short always-on pointer at that
257
+ canonical agent prompt and tells agents to use the `memex` CLI (and
258
+ `memex llms` for the full reference); `src/memex/templates/llms.txt` is that
259
+ reference. The Cursor `.mdc` is a short always-on pointer at that
231
260
  block (Claude gets the same block in `CLAUDE.md`). Cursor skills live
232
261
  under `templates/skills/` and are copied into the target repo's
233
262
  `.cursor/skills/` (today: `memex-hygiene` to audit stale/stacked notes;
234
263
  user-invoked only). The agent files tell agents to
235
- **`recall` (MUST) before non-trivial / unfamiliar work, when debugging, and
264
+ **`memex recall` (MUST) before non-trivial / unfamiliar work, when debugging, and
236
265
  when choices depend on project or business rules**, with sample queries and
237
- skip criteria for trivial edits, and to **`remember` durable decisions,
266
+ skip criteria for trivial edits, and to **`memex remember` durable decisions,
238
267
  project/business rules, and solved problems** (symptoms → cause → fix).
239
- If a new fact supersedes an old note, agents should pass `replaces=<id>` (or
240
- `forget` the old id) rather than stacking a second memory. `list` catalogs
241
- what is stored; do not dummy-`recall` with a large `k`.
268
+ If a new fact supersedes an old note, agents should pass `--replaces <id>` (or
269
+ `memex forget` the old id) rather than stacking a second memory. `memex list`
270
+ catalogs what is stored; do not dummy-recall with a large `-k`.
242
271
 
243
272
  ## Environment
244
273
 
@@ -255,7 +284,7 @@ what is stored; do not dummy-`recall` with a large `k`.
255
284
  |---------|-----|
256
285
  | `command not found: python` | Use `python3` (common on Linux/WSL) |
257
286
  | `command not found: memex` | Activate the venv, use `.venv/bin/memex`, or install globally (`uv tool install git-memex` / `pipx install git-memex`) |
258
- | `spawn … memex ENOENT` | Wrong or missing binary — default is `${userHome}/.local/bin/memex`; override with `--command` or install via `uv tool install git-memex` |
287
+ | `spawn … memex ENOENT` (MCP) | Wrong or missing binary — default is `${userHome}/.local/bin/memex`; override with `--command` or install via `uv tool install git-memex` |
259
288
  | `not a git repository` | Open a git checkout, or set `MEMEX_ROOT` to the repo root |
260
289
  | `sqlite-vec is not installed` / extension load failed | Use a CPython build that supports loadable extensions (not some OS-default Pythons); `pip install sqlite-vec` |
261
290
  | `MODEL.json pins … but embedder is …` | Same model for the whole team, or `memex reindex --force` after intentional model change |
@@ -2,7 +2,10 @@
2
2
 
3
3
  Repo-local vector memory for AI agents. Memories live **inside the git repository**
4
4
  as mergeable markdown notes plus a rebuildable sqlite-vec index. Use the `memex`
5
- CLI or a stdio MCP server to `remember` and `recall` by semantic relevance.
5
+ CLI to `remember` and `recall` by semantic relevance. The CLI is the primary
6
+ interface, so it works in any LLM harness that can run shell commands; agents
7
+ get a full usage guide from `memex llms` (an `llms.txt`). A stdio MCP server
8
+ (`memex serve`) is available as an opt-in extra.
6
9
 
7
10
  Published on PyPI as [`git-memex`](https://pypi.org/project/git-memex/) (`memex` was already taken).
8
11
 
@@ -45,10 +48,11 @@ uv run pytest
45
48
 
46
49
  On Linux/WSL, use `python3` if `python` is not found.
47
50
 
48
- ## Cursor MCP config
51
+ ## Optional MCP config
49
52
 
50
- Prefer **`memex install cursor`** in the target repo — it writes `.cursor/mcp.json`
51
- with a portable home path (after `uv tool install` / `pipx`):
53
+ Agents use the CLI by default. To also register the MCP server, pass `--mcp`:
54
+ **`memex install cursor --mcp`** writes `.cursor/mcp.json` with a portable home
55
+ path (after `uv tool install` / `pipx`):
52
56
 
53
57
  ```json
54
58
  {
@@ -74,15 +78,23 @@ the server walks parents from the process cwd looking for `.git`.
74
78
 
75
79
  ## Claude Desktop / Claude Code
76
80
 
77
- For Claude Code, prefer **`memex install claude`** (writes project `.mcp.json` +
78
- `CLAUDE.md`). Default command is bare `memex` (on PATH). See
79
- `examples/claude-mcp.json`.
81
+ For Claude Code, prefer **`memex install claude`** (writes `CLAUDE.md`; add
82
+ `--mcp` for project `.mcp.json`). Default MCP command is bare `memex` (on PATH).
83
+ See `examples/claude-mcp.json`.
80
84
 
81
85
  ## Codex
82
86
 
83
- Prefer **`memex install codex`**. Default command is bare `memex`; Codex still
87
+ Prefer **`memex install codex`** (writes `AGENTS.md`; add `--mcp` for the
88
+ `.codex/config.toml` block). Default MCP command is bare `memex`; Codex still
84
89
  gets an absolute `MEMEX_ROOT` for the repo. See `examples/codex-config.toml`.
85
90
 
91
+ ## Any other harness
92
+
93
+ **`memex install agents`** writes only the CLI-first Memex block to `AGENTS.md`
94
+ (plus `.memex/` layout and `.gitattributes`). Any agent that reads `AGENTS.md`
95
+ and can run shell commands can then use Memex; point it at `memex llms` for
96
+ the full reference.
97
+
86
98
  ## On-disk layout
87
99
 
88
100
  ```text
@@ -101,16 +113,21 @@ pull that changes notes, the next `recall` auto-reindexes if the DB is stale.
101
113
  ## CLI
102
114
 
103
115
  After install, the `memex` console script is a CLI. Running `memex` with no
104
- arguments prints help. Start the MCP server with `memex serve`.
116
+ arguments prints help. `memex llms` prints the agent guide (`llms.txt`: workflow,
117
+ every command and flag, JSON shapes). Start the optional MCP server with
118
+ `memex serve`.
105
119
 
106
120
  ```bash
107
121
  memex # show help
108
122
  memex help
109
123
  memex help install
110
- memex install cursor # Cursor rule + MCP + .cursor/skills
111
- memex install claude # CLAUDE.md + .mcp.json
112
- memex install codex # AGENTS.md + .codex/config.toml MCP
124
+ memex llms # agent/LLM usage guide (llms.txt)
125
+ memex install agents # AGENTS.md only (any harness)
126
+ memex install cursor # AGENTS.md + Cursor rule + .cursor/skills
127
+ memex install claude # AGENTS.md + CLAUDE.md
128
+ memex install codex # AGENTS.md
113
129
  memex install all
130
+ memex install all --mcp # also write MCP server configs
114
131
  memex status
115
132
  memex list
116
133
  memex list --tags decision --limit 20
@@ -118,12 +135,14 @@ memex list --tags-all auth,decision --offset 20 --limit 20
118
135
  memex reindex # rebuild memory.db from .memex/notes
119
136
  memex reindex --force # rebuild even when fingerprints match
120
137
  memex remember "We use JWT in httpOnly cookies" --tags auth,decision
138
+ memex remember "Auth lives in the cookie middleware" --tags auth,bugfix --paths src/auth/
121
139
  memex remember "Strip locale from JWT" --replaces <uuid>
140
+ echo "Fact with \"quotes\"" | memex remember - --tags convention # read from stdin
122
141
  memex recall "how is auth handled?" -k 5
123
142
  memex recall "how is auth handled?" --tags-all auth,security --recency
124
143
  memex recall "how is auth handled?" --rank blended
125
144
  memex forget <uuid>
126
- memex serve # stdio MCP server
145
+ memex serve # optional stdio MCP server
127
146
  ```
128
147
 
129
148
  Add `--json` to any command for machine-readable output. From a checkout:
@@ -134,13 +153,15 @@ make reindex
134
153
  make reindex FORCE=1
135
154
  ```
136
155
 
137
- ## MCP tools
156
+ ## MCP tools (optional)
157
+
158
+ `memex serve` exposes the same operations as MCP tools:
138
159
 
139
160
  | Tool | Purpose |
140
161
  |------|---------|
141
- | `remember` | Store a memory; skips/updates near-duplicates & elaborations; `replaces` updates by id |
142
- | `recall` | Semantic KNN search; returns untrusted evidence with timestamps |
143
- | `list` | Catalog notes (id, first line, tags, dates) without embeddings |
162
+ | `remember` | Store a memory; skips/updates near-duplicates & elaborations; `replaces` updates by id; optional `paths` for related scope |
163
+ | `recall` | Semantic KNN search; returns untrusted evidence with timestamps and optional `paths` |
164
+ | `list` | Catalog notes (id, first line, tags, paths, dates) without embeddings |
144
165
  | `reindex` | Rebuild `memory.db` from notes |
145
166
  | `forget` | Delete a memory by id |
146
167
  | `status` | Repo root, counts, tag histogram, model, staleness |
@@ -151,6 +172,8 @@ tag; `--tags-all` requires every listed tag. `--recency` applies a bounded
151
172
  freshness boost with a 30-day half-life. `--rank blended` opts into combined
152
173
  semantic, freshness, tag-overlap, and type-tag ranking; cosine remains the
153
174
  default and the returned `score` remains raw cosine similarity.
175
+ Optional `paths` on `remember` (comma-separated repo-relative files/folders) is
176
+ durable related scope for bugfixes and module conventions—not a session diff.
154
177
  When `remember` inserts a new note that is close to an existing one, the response
155
178
  includes `conflicts` and may include advisory `suggested_tags`. Recall hits may
156
179
  include `conflict: true` when multiple near-neighbor notes could represent
@@ -171,11 +194,13 @@ verify important notes against the repository.
171
194
  In any git repository where agents should use Memex, install for your platform(s):
172
195
 
173
196
  ```bash
197
+ memex install agents # AGENTS.md only — any harness
174
198
  memex install cursor
175
199
  memex install claude
176
200
  memex install codex
177
- memex install all # cursor + claude + codex
201
+ memex install all # agents + cursor + claude + codex
178
202
  memex install cursor claude # multiple targets
203
+ memex install all --mcp # also write MCP server configs
179
204
  ```
180
205
 
181
206
  Every target is idempotent and always:
@@ -189,27 +214,31 @@ Platform extras:
189
214
 
190
215
  | Target | Also writes |
191
216
  |--------|-------------|
192
- | `cursor` | short always-on `.cursor/rules/memex.mdc` (points at the `AGENTS.md` Memex block), `.cursor/mcp.json` (`${userHome}/…`, `MEMEX_ROOT=${workspaceFolder}`), `.cursor/skills/` from `templates/skills/` |
193
- | `claude` | `CLAUDE.md`, `.mcp.json` (`command: memex`, `MEMEX_ROOT=${CLAUDE_PROJECT_DIR:-.}`) |
194
- | `codex` | `.codex/config.toml` MCP block (`command: memex`, absolute `MEMEX_ROOT`) |
217
+ | `agents` | nothing else |
218
+ | `cursor` | short always-on `.cursor/rules/memex.mdc` (points at the `AGENTS.md` Memex block), `.cursor/skills/` from `templates/skills/`; with `--mcp`: `.cursor/mcp.json` (`${userHome}/…`, `MEMEX_ROOT=${workspaceFolder}`) |
219
+ | `claude` | `CLAUDE.md`; with `--mcp`: `.mcp.json` (`command: memex`, `MEMEX_ROOT=${CLAUDE_PROJECT_DIR:-.}`) |
220
+ | `codex` | with `--mcp`: `.codex/config.toml` MCP block (`command: memex`, absolute `MEMEX_ROOT`) |
195
221
 
196
222
  Re-run after upgrading `git-memex` to refresh prompts from packaged templates.
197
- Flags: `--no-agents`, `--no-instructions`, `--no-rules`, `--no-mcp`,
198
- `--no-skills`, `--no-gitattributes`, `--command /path/to/memex`.
223
+ Flags: `--mcp`, `--no-agents`, `--no-instructions`, `--no-rules`,
224
+ `--no-skills`, `--no-gitattributes`, `--command /path/to/memex` (MCP binary).
225
+ Re-running without `--mcp` never removes MCP config written earlier.
199
226
 
200
227
  Templates live in the package (`src/memex/templates/`). `AGENTS.md` is the
201
- canonical agent prompt; the Cursor `.mdc` is a short always-on pointer at that
228
+ canonical agent prompt and tells agents to use the `memex` CLI (and
229
+ `memex llms` for the full reference); `src/memex/templates/llms.txt` is that
230
+ reference. The Cursor `.mdc` is a short always-on pointer at that
202
231
  block (Claude gets the same block in `CLAUDE.md`). Cursor skills live
203
232
  under `templates/skills/` and are copied into the target repo's
204
233
  `.cursor/skills/` (today: `memex-hygiene` to audit stale/stacked notes;
205
234
  user-invoked only). The agent files tell agents to
206
- **`recall` (MUST) before non-trivial / unfamiliar work, when debugging, and
235
+ **`memex recall` (MUST) before non-trivial / unfamiliar work, when debugging, and
207
236
  when choices depend on project or business rules**, with sample queries and
208
- skip criteria for trivial edits, and to **`remember` durable decisions,
237
+ skip criteria for trivial edits, and to **`memex remember` durable decisions,
209
238
  project/business rules, and solved problems** (symptoms → cause → fix).
210
- If a new fact supersedes an old note, agents should pass `replaces=<id>` (or
211
- `forget` the old id) rather than stacking a second memory. `list` catalogs
212
- what is stored; do not dummy-`recall` with a large `k`.
239
+ If a new fact supersedes an old note, agents should pass `--replaces <id>` (or
240
+ `memex forget` the old id) rather than stacking a second memory. `memex list`
241
+ catalogs what is stored; do not dummy-recall with a large `-k`.
213
242
 
214
243
  ## Environment
215
244
 
@@ -226,7 +255,7 @@ what is stored; do not dummy-`recall` with a large `k`.
226
255
  |---------|-----|
227
256
  | `command not found: python` | Use `python3` (common on Linux/WSL) |
228
257
  | `command not found: memex` | Activate the venv, use `.venv/bin/memex`, or install globally (`uv tool install git-memex` / `pipx install git-memex`) |
229
- | `spawn … memex ENOENT` | Wrong or missing binary — default is `${userHome}/.local/bin/memex`; override with `--command` or install via `uv tool install git-memex` |
258
+ | `spawn … memex ENOENT` (MCP) | Wrong or missing binary — default is `${userHome}/.local/bin/memex`; override with `--command` or install via `uv tool install git-memex` |
230
259
  | `not a git repository` | Open a git checkout, or set `MEMEX_ROOT` to the repo root |
231
260
  | `sqlite-vec is not installed` / extension load failed | Use a CPython build that supports loadable extensions (not some OS-default Pythons); `pip install sqlite-vec` |
232
261
  | `MODEL.json pins … but embedder is …` | Same model for the whole team, or `memex reindex --force` after intentional model change |
@@ -1,7 +1,7 @@
1
1
  [project]
2
2
  name = "git-memex"
3
- version = "0.3.2"
4
- description = "Memex: repo-local vector memory — CLI + MCP remember/recall inside the git repository"
3
+ version = "0.4.0"
4
+ description = "Memex: repo-local vector memory for AI agents — CLI-first remember/recall inside the git repository (optional MCP)"
5
5
  readme = "README.md"
6
6
  license = "MIT"
7
7
  requires-python = ">=3.11"
@@ -9,6 +9,8 @@ authors = [
9
9
  { name = "Daniel" },
10
10
  ]
11
11
  keywords = [
12
+ "cli",
13
+ "llms-txt",
12
14
  "mcp",
13
15
  "agent-memory",
14
16
  "vector-search",