git-memex 0.3.3__tar.gz → 0.4.0__tar.gz

{git_memex-0.3.3 → git_memex-0.4.0}/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## Unreleased
 
+## 0.4.0 — 2026-11-10
+
+- **CLI-first agent integration.** Agent prompts (`AGENTS.md` block, Cursor
+  rule, `memex-hygiene` skill) now tell agents to run the `memex` CLI
+  (`memex recall "…"`, `memex remember "…" --tags …`) instead of MCP tools, so
+  Memex works in any harness that can run shell commands.
+- New `memex llms` (alias `memex llms.txt`): prints an `llms.txt`-style agent
+  guide — workflow, every command and flag, JSON shapes, env vars.
+- `memex remember -` reads the fact from stdin (avoids shell quoting).
+- New install target `agents`: writes only the `AGENTS.md` block + layout, for
+  harnesses without dedicated wiring. `all` now includes it.
+- **Breaking:** `memex install` no longer writes MCP config by default; pass
+  `--mcp` to write `.cursor/mcp.json` / `.mcp.json` / `.codex/config.toml`.
+  `--no-mcp` is still accepted (now a no-op). Existing MCP config is left as is.
+- Fixed a date-dependent recency ranking test that failed once its fixed
+  "fresh" timestamp aged past the 30-day half-life.
+
 ## 0.3.3 — 2026-09-06
 
 - Optional note **`paths`**: durable related scope (repo-relative files/folders)

{git_memex-0.3.3/src/git_memex.egg-info → git_memex-0.4.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: git-memex
-Version: 0.3.3
-Summary: Memex: repo-local vector memory — CLI + MCP remember/recall inside the git repository
+Version: 0.4.0
+Summary: Memex: repo-local vector memory for AI agents — CLI-first remember/recall inside the git repository (optional MCP)
 Author: Daniel
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/daniel/memex
 Project-URL: Repository, https://github.com/daniel/memex
-Keywords: mcp,agent-memory,vector-search,sqlite-vec,git
+Keywords: cli,llms-txt,mcp,agent-memory,vector-search,sqlite-vec,git
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
@@ -31,7 +31,10 @@ Dynamic: license-file
 
 Repo-local vector memory for AI agents. Memories live **inside the git repository**
 as mergeable markdown notes plus a rebuildable sqlite-vec index. Use the `memex`
-CLI or a stdio MCP server to `remember` and `recall` by semantic relevance.
+CLI to `remember` and `recall` by semantic relevance. The CLI is the primary
+interface, so it works in any LLM harness that can run shell commands; agents
+get a full usage guide from `memex llms` (an `llms.txt`). A stdio MCP server
+(`memex serve`) is available as an opt-in extra.
 
 Published on PyPI as [`git-memex`](https://pypi.org/project/git-memex/) (`memex` was already taken).
 
@@ -74,10 +77,11 @@ uv run pytest
 
 On Linux/WSL, use `python3` if `python` is not found.
 
-## Cursor MCP config
+## Optional MCP config
 
-Prefer **`memex install cursor`** in the target repo — it writes `.cursor/mcp.json`
-with a portable home path (after `uv tool install` / `pipx`):
+Agents use the CLI by default. To also register the MCP server, pass `--mcp`:
+**`memex install cursor --mcp`** writes `.cursor/mcp.json` with a portable home
+path (after `uv tool install` / `pipx`):
 
 ```json
 {
@@ -103,15 +107,23 @@ the server walks parents from the process cwd looking for `.git`.
 
 ## Claude Desktop / Claude Code
 
-For Claude Code, prefer **`memex install claude`** (writes project `.mcp.json` +
-`CLAUDE.md`). Default command is bare `memex` (on PATH). See
-`examples/claude-mcp.json`.
+For Claude Code, prefer **`memex install claude`** (writes `CLAUDE.md`; add
+`--mcp` for project `.mcp.json`). Default MCP command is bare `memex` (on PATH).
+See `examples/claude-mcp.json`.
 
 ## Codex
 
-Prefer **`memex install codex`**. Default command is bare `memex`; Codex still
+Prefer **`memex install codex`** (writes `AGENTS.md`; add `--mcp` for the
+`.codex/config.toml` block). Default MCP command is bare `memex`; Codex still
 gets an absolute `MEMEX_ROOT` for the repo. See `examples/codex-config.toml`.
 
+## Any other harness
+
+**`memex install agents`** writes only the CLI-first Memex block to `AGENTS.md`
+(plus `.memex/` layout and `.gitattributes`). Any agent that reads `AGENTS.md`
+and can run shell commands can then use Memex; point it at `memex llms` for
+the full reference.
+
 ## On-disk layout
 
 ```text
@@ -130,16 +142,21 @@ pull that changes notes, the next `recall` auto-reindexes if the DB is stale.
 ## CLI
 
 After install, the `memex` console script is a CLI. Running `memex` with no
-arguments prints help. Start the MCP server with `memex serve`.
+arguments prints help. `memex llms` prints the agent guide (`llms.txt`: workflow,
+every command and flag, JSON shapes). Start the optional MCP server with
+`memex serve`.
 
 ```bash
 memex                      # show help
 memex help
 memex help install
-memex install cursor       # Cursor rule + MCP + .cursor/skills
-memex install claude       # CLAUDE.md + .mcp.json
-memex install codex        # AGENTS.md + .codex/config.toml MCP
+memex llms                 # agent/LLM usage guide (llms.txt)
+memex install agents       # AGENTS.md only (any harness)
+memex install cursor       # AGENTS.md + Cursor rule + .cursor/skills
+memex install claude       # AGENTS.md + CLAUDE.md
+memex install codex        # AGENTS.md
 memex install all
+memex install all --mcp    # also write MCP server configs
 memex status
 memex list
 memex list --tags decision --limit 20
@@ -149,11 +166,12 @@ memex reindex --force      # rebuild even when fingerprints match
 memex remember "We use JWT in httpOnly cookies" --tags auth,decision
 memex remember "Auth lives in the cookie middleware" --tags auth,bugfix --paths src/auth/
 memex remember "Strip locale from JWT" --replaces <uuid>
+echo "Fact with \"quotes\"" | memex remember - --tags convention   # read from stdin
 memex recall "how is auth handled?" -k 5
 memex recall "how is auth handled?" --tags-all auth,security --recency
 memex recall "how is auth handled?" --rank blended
 memex forget <uuid>
-memex serve                # stdio MCP server
+memex serve                # optional stdio MCP server
 ```
 
 Add `--json` to any command for machine-readable output. From a checkout:
@@ -164,7 +182,9 @@ make reindex
 make reindex FORCE=1
 ```
 
-## MCP tools
+## MCP tools (optional)
+
+`memex serve` exposes the same operations as MCP tools:
 
 | Tool | Purpose |
 |------|---------|
@@ -203,11 +223,13 @@ verify important notes against the repository.
 In any git repository where agents should use Memex, install for your platform(s):
 
 ```bash
+memex install agents           # AGENTS.md only — any harness
 memex install cursor
 memex install claude
 memex install codex
-memex install all              # cursor + claude + codex
+memex install all              # agents + cursor + claude + codex
 memex install cursor claude    # multiple targets
+memex install all --mcp        # also write MCP server configs
 ```
 
 Every target is idempotent and always:
@@ -221,27 +243,31 @@ Platform extras:
 
 | Target | Also writes |
 |--------|-------------|
-| `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/` |
-| `claude` | `CLAUDE.md`, `.mcp.json` (`command: memex`, `MEMEX_ROOT=${CLAUDE_PROJECT_DIR:-.}`) |
-| `codex` | `.codex/config.toml` MCP block (`command: memex`, absolute `MEMEX_ROOT`) |
+| `agents` | nothing else |
+| `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}`) |
+| `claude` | `CLAUDE.md`; with `--mcp`: `.mcp.json` (`command: memex`, `MEMEX_ROOT=${CLAUDE_PROJECT_DIR:-.}`) |
+| `codex` | with `--mcp`: `.codex/config.toml` MCP block (`command: memex`, absolute `MEMEX_ROOT`) |
 
 Re-run after upgrading `git-memex` to refresh prompts from packaged templates.
-Flags: `--no-agents`, `--no-instructions`, `--no-rules`, `--no-mcp`,
-`--no-skills`, `--no-gitattributes`, `--command /path/to/memex`.
+Flags: `--mcp`, `--no-agents`, `--no-instructions`, `--no-rules`,
+`--no-skills`, `--no-gitattributes`, `--command /path/to/memex` (MCP binary).
+Re-running without `--mcp` never removes MCP config written earlier.
 
 Templates live in the package (`src/memex/templates/`). `AGENTS.md` is the
-canonical agent prompt; the Cursor `.mdc` is a short always-on pointer at that
+canonical agent prompt and tells agents to use the `memex` CLI (and
+`memex llms` for the full reference); `src/memex/templates/llms.txt` is that
+reference. The Cursor `.mdc` is a short always-on pointer at that
 block (Claude gets the same block in `CLAUDE.md`). Cursor skills live
 under `templates/skills/` and are copied into the target repo's
 `.cursor/skills/` (today: `memex-hygiene` to audit stale/stacked notes;
 user-invoked only). The agent files tell agents to
-**`recall` (MUST) before non-trivial / unfamiliar work, when debugging, and
+**`memex recall` (MUST) before non-trivial / unfamiliar work, when debugging, and
 when choices depend on project or business rules**, with sample queries and
-skip criteria for trivial edits, and to **`remember` durable decisions,
+skip criteria for trivial edits, and to **`memex remember` durable decisions,
 project/business rules, and solved problems** (symptoms → cause → fix).
-If a new fact supersedes an old note, agents should pass `replaces=<id>` (or
-`forget` the old id) rather than stacking a second memory. `list` catalogs
-what is stored; do not dummy-`recall` with a large `k`.
+If a new fact supersedes an old note, agents should pass `--replaces <id>` (or
+`memex forget` the old id) rather than stacking a second memory. `memex list`
+catalogs what is stored; do not dummy-recall with a large `-k`.
 
 ## Environment
 
@@ -258,7 +284,7 @@ what is stored; do not dummy-`recall` with a large `k`.
 |---------|-----|
 | `command not found: python` | Use `python3` (common on Linux/WSL) |
 | `command not found: memex` | Activate the venv, use `.venv/bin/memex`, or install globally (`uv tool install git-memex` / `pipx install git-memex`) |
-| `spawn … memex ENOENT` | Wrong or missing binary — default is `${userHome}/.local/bin/memex`; override with `--command` or install via `uv tool install git-memex` |
+| `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` |
 | `not a git repository` | Open a git checkout, or set `MEMEX_ROOT` to the repo root |
 | `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` |
 | `MODEL.json pins … but embedder is …` | Same model for the whole team, or `memex reindex --force` after intentional model change |

{git_memex-0.3.3 → git_memex-0.4.0}/README.md

@@ -2,7 +2,10 @@
 
 Repo-local vector memory for AI agents. Memories live **inside the git repository**
 as mergeable markdown notes plus a rebuildable sqlite-vec index. Use the `memex`
-CLI or a stdio MCP server to `remember` and `recall` by semantic relevance.
+CLI to `remember` and `recall` by semantic relevance. The CLI is the primary
+interface, so it works in any LLM harness that can run shell commands; agents
+get a full usage guide from `memex llms` (an `llms.txt`). A stdio MCP server
+(`memex serve`) is available as an opt-in extra.
 
 Published on PyPI as [`git-memex`](https://pypi.org/project/git-memex/) (`memex` was already taken).
 
@@ -45,10 +48,11 @@ uv run pytest
 
 On Linux/WSL, use `python3` if `python` is not found.
 
-## Cursor MCP config
+## Optional MCP config
 
-Prefer **`memex install cursor`** in the target repo — it writes `.cursor/mcp.json`
-with a portable home path (after `uv tool install` / `pipx`):
+Agents use the CLI by default. To also register the MCP server, pass `--mcp`:
+**`memex install cursor --mcp`** writes `.cursor/mcp.json` with a portable home
+path (after `uv tool install` / `pipx`):
 
 ```json
 {
@@ -74,15 +78,23 @@ the server walks parents from the process cwd looking for `.git`.
 
 ## Claude Desktop / Claude Code
 
-For Claude Code, prefer **`memex install claude`** (writes project `.mcp.json` +
-`CLAUDE.md`). Default command is bare `memex` (on PATH). See
-`examples/claude-mcp.json`.
+For Claude Code, prefer **`memex install claude`** (writes `CLAUDE.md`; add
+`--mcp` for project `.mcp.json`). Default MCP command is bare `memex` (on PATH).
+See `examples/claude-mcp.json`.
 
 ## Codex
 
-Prefer **`memex install codex`**. Default command is bare `memex`; Codex still
+Prefer **`memex install codex`** (writes `AGENTS.md`; add `--mcp` for the
+`.codex/config.toml` block). Default MCP command is bare `memex`; Codex still
 gets an absolute `MEMEX_ROOT` for the repo. See `examples/codex-config.toml`.
 
+## Any other harness
+
+**`memex install agents`** writes only the CLI-first Memex block to `AGENTS.md`
+(plus `.memex/` layout and `.gitattributes`). Any agent that reads `AGENTS.md`
+and can run shell commands can then use Memex; point it at `memex llms` for
+the full reference.
+
 ## On-disk layout
 
 ```text
@@ -101,16 +113,21 @@ pull that changes notes, the next `recall` auto-reindexes if the DB is stale.
 ## CLI
 
 After install, the `memex` console script is a CLI. Running `memex` with no
-arguments prints help. Start the MCP server with `memex serve`.
+arguments prints help. `memex llms` prints the agent guide (`llms.txt`: workflow,
+every command and flag, JSON shapes). Start the optional MCP server with
+`memex serve`.
 
 ```bash
 memex                      # show help
 memex help
 memex help install
-memex install cursor       # Cursor rule + MCP + .cursor/skills
-memex install claude       # CLAUDE.md + .mcp.json
-memex install codex        # AGENTS.md + .codex/config.toml MCP
+memex llms                 # agent/LLM usage guide (llms.txt)
+memex install agents       # AGENTS.md only (any harness)
+memex install cursor       # AGENTS.md + Cursor rule + .cursor/skills
+memex install claude       # AGENTS.md + CLAUDE.md
+memex install codex        # AGENTS.md
 memex install all
+memex install all --mcp    # also write MCP server configs
 memex status
 memex list
 memex list --tags decision --limit 20
@@ -120,11 +137,12 @@ memex reindex --force      # rebuild even when fingerprints match
 memex remember "We use JWT in httpOnly cookies" --tags auth,decision
 memex remember "Auth lives in the cookie middleware" --tags auth,bugfix --paths src/auth/
 memex remember "Strip locale from JWT" --replaces <uuid>
+echo "Fact with \"quotes\"" | memex remember - --tags convention   # read from stdin
 memex recall "how is auth handled?" -k 5
 memex recall "how is auth handled?" --tags-all auth,security --recency
 memex recall "how is auth handled?" --rank blended
 memex forget <uuid>
-memex serve                # stdio MCP server
+memex serve                # optional stdio MCP server
 ```
 
 Add `--json` to any command for machine-readable output. From a checkout:
@@ -135,7 +153,9 @@ make reindex
 make reindex FORCE=1
 ```
 
-## MCP tools
+## MCP tools (optional)
+
+`memex serve` exposes the same operations as MCP tools:
 
 | Tool | Purpose |
 |------|---------|
@@ -174,11 +194,13 @@ verify important notes against the repository.
 In any git repository where agents should use Memex, install for your platform(s):
 
 ```bash
+memex install agents           # AGENTS.md only — any harness
 memex install cursor
 memex install claude
 memex install codex
-memex install all              # cursor + claude + codex
+memex install all              # agents + cursor + claude + codex
 memex install cursor claude    # multiple targets
+memex install all --mcp        # also write MCP server configs
 ```
 
 Every target is idempotent and always:
@@ -192,27 +214,31 @@ Platform extras:
 
 | Target | Also writes |
 |--------|-------------|
-| `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/` |
-| `claude` | `CLAUDE.md`, `.mcp.json` (`command: memex`, `MEMEX_ROOT=${CLAUDE_PROJECT_DIR:-.}`) |
-| `codex` | `.codex/config.toml` MCP block (`command: memex`, absolute `MEMEX_ROOT`) |
+| `agents` | nothing else |
+| `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}`) |
+| `claude` | `CLAUDE.md`; with `--mcp`: `.mcp.json` (`command: memex`, `MEMEX_ROOT=${CLAUDE_PROJECT_DIR:-.}`) |
+| `codex` | with `--mcp`: `.codex/config.toml` MCP block (`command: memex`, absolute `MEMEX_ROOT`) |
 
 Re-run after upgrading `git-memex` to refresh prompts from packaged templates.
-Flags: `--no-agents`, `--no-instructions`, `--no-rules`, `--no-mcp`,
-`--no-skills`, `--no-gitattributes`, `--command /path/to/memex`.
+Flags: `--mcp`, `--no-agents`, `--no-instructions`, `--no-rules`,
+`--no-skills`, `--no-gitattributes`, `--command /path/to/memex` (MCP binary).
+Re-running without `--mcp` never removes MCP config written earlier.
 
 Templates live in the package (`src/memex/templates/`). `AGENTS.md` is the
-canonical agent prompt; the Cursor `.mdc` is a short always-on pointer at that
+canonical agent prompt and tells agents to use the `memex` CLI (and
+`memex llms` for the full reference); `src/memex/templates/llms.txt` is that
+reference. The Cursor `.mdc` is a short always-on pointer at that
 block (Claude gets the same block in `CLAUDE.md`). Cursor skills live
 under `templates/skills/` and are copied into the target repo's
 `.cursor/skills/` (today: `memex-hygiene` to audit stale/stacked notes;
 user-invoked only). The agent files tell agents to
-**`recall` (MUST) before non-trivial / unfamiliar work, when debugging, and
+**`memex recall` (MUST) before non-trivial / unfamiliar work, when debugging, and
 when choices depend on project or business rules**, with sample queries and
-skip criteria for trivial edits, and to **`remember` durable decisions,
+skip criteria for trivial edits, and to **`memex remember` durable decisions,
 project/business rules, and solved problems** (symptoms → cause → fix).
-If a new fact supersedes an old note, agents should pass `replaces=<id>` (or
-`forget` the old id) rather than stacking a second memory. `list` catalogs
-what is stored; do not dummy-`recall` with a large `k`.
+If a new fact supersedes an old note, agents should pass `--replaces <id>` (or
+`memex forget` the old id) rather than stacking a second memory. `memex list`
+catalogs what is stored; do not dummy-recall with a large `-k`.
 
 ## Environment
 
@@ -229,7 +255,7 @@ what is stored; do not dummy-`recall` with a large `k`.
 |---------|-----|
 | `command not found: python` | Use `python3` (common on Linux/WSL) |
 | `command not found: memex` | Activate the venv, use `.venv/bin/memex`, or install globally (`uv tool install git-memex` / `pipx install git-memex`) |
-| `spawn … memex ENOENT` | Wrong or missing binary — default is `${userHome}/.local/bin/memex`; override with `--command` or install via `uv tool install git-memex` |
+| `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` |
 | `not a git repository` | Open a git checkout, or set `MEMEX_ROOT` to the repo root |
 | `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` |
 | `MODEL.json pins … but embedder is …` | Same model for the whole team, or `memex reindex --force` after intentional model change |

{git_memex-0.3.3 → git_memex-0.4.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "git-memex"
-version = "0.3.3"
-description = "Memex: repo-local vector memory — CLI + MCP remember/recall inside the git repository"
+version = "0.4.0"
+description = "Memex: repo-local vector memory for AI agents — CLI-first remember/recall inside the git repository (optional MCP)"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.11"
@@ -9,6 +9,8 @@ authors = [
     { name = "Daniel" },
 ]
 keywords = [
+    "cli",
+    "llms-txt",
     "mcp",
     "agent-memory",
     "vector-search",

{git_memex-0.3.3 → git_memex-0.4.0/src/git_memex.egg-info}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: git-memex
-Version: 0.3.3
-Summary: Memex: repo-local vector memory — CLI + MCP remember/recall inside the git repository
+Version: 0.4.0
+Summary: Memex: repo-local vector memory for AI agents — CLI-first remember/recall inside the git repository (optional MCP)
 Author: Daniel
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/daniel/memex
 Project-URL: Repository, https://github.com/daniel/memex
-Keywords: mcp,agent-memory,vector-search,sqlite-vec,git
+Keywords: cli,llms-txt,mcp,agent-memory,vector-search,sqlite-vec,git
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
@@ -31,7 +31,10 @@ Dynamic: license-file
 
 Repo-local vector memory for AI agents. Memories live **inside the git repository**
 as mergeable markdown notes plus a rebuildable sqlite-vec index. Use the `memex`
-CLI or a stdio MCP server to `remember` and `recall` by semantic relevance.
+CLI to `remember` and `recall` by semantic relevance. The CLI is the primary
+interface, so it works in any LLM harness that can run shell commands; agents
+get a full usage guide from `memex llms` (an `llms.txt`). A stdio MCP server
+(`memex serve`) is available as an opt-in extra.
 
 Published on PyPI as [`git-memex`](https://pypi.org/project/git-memex/) (`memex` was already taken).
 
@@ -74,10 +77,11 @@ uv run pytest
 
 On Linux/WSL, use `python3` if `python` is not found.
 
-## Cursor MCP config
+## Optional MCP config
 
-Prefer **`memex install cursor`** in the target repo — it writes `.cursor/mcp.json`
-with a portable home path (after `uv tool install` / `pipx`):
+Agents use the CLI by default. To also register the MCP server, pass `--mcp`:
+**`memex install cursor --mcp`** writes `.cursor/mcp.json` with a portable home
+path (after `uv tool install` / `pipx`):
 
 ```json
 {
@@ -103,15 +107,23 @@ the server walks parents from the process cwd looking for `.git`.
 
 ## Claude Desktop / Claude Code
 
-For Claude Code, prefer **`memex install claude`** (writes project `.mcp.json` +
-`CLAUDE.md`). Default command is bare `memex` (on PATH). See
-`examples/claude-mcp.json`.
+For Claude Code, prefer **`memex install claude`** (writes `CLAUDE.md`; add
+`--mcp` for project `.mcp.json`). Default MCP command is bare `memex` (on PATH).
+See `examples/claude-mcp.json`.
 
 ## Codex
 
-Prefer **`memex install codex`**. Default command is bare `memex`; Codex still
+Prefer **`memex install codex`** (writes `AGENTS.md`; add `--mcp` for the
+`.codex/config.toml` block). Default MCP command is bare `memex`; Codex still
 gets an absolute `MEMEX_ROOT` for the repo. See `examples/codex-config.toml`.
 
+## Any other harness
+
+**`memex install agents`** writes only the CLI-first Memex block to `AGENTS.md`
+(plus `.memex/` layout and `.gitattributes`). Any agent that reads `AGENTS.md`
+and can run shell commands can then use Memex; point it at `memex llms` for
+the full reference.
+
 ## On-disk layout
 
 ```text
@@ -130,16 +142,21 @@ pull that changes notes, the next `recall` auto-reindexes if the DB is stale.
 ## CLI
 
 After install, the `memex` console script is a CLI. Running `memex` with no
-arguments prints help. Start the MCP server with `memex serve`.
+arguments prints help. `memex llms` prints the agent guide (`llms.txt`: workflow,
+every command and flag, JSON shapes). Start the optional MCP server with
+`memex serve`.
 
 ```bash
 memex                      # show help
 memex help
 memex help install
-memex install cursor       # Cursor rule + MCP + .cursor/skills
-memex install claude       # CLAUDE.md + .mcp.json
-memex install codex        # AGENTS.md + .codex/config.toml MCP
+memex llms                 # agent/LLM usage guide (llms.txt)
+memex install agents       # AGENTS.md only (any harness)
+memex install cursor       # AGENTS.md + Cursor rule + .cursor/skills
+memex install claude       # AGENTS.md + CLAUDE.md
+memex install codex        # AGENTS.md
 memex install all
+memex install all --mcp    # also write MCP server configs
 memex status
 memex list
 memex list --tags decision --limit 20
@@ -149,11 +166,12 @@ memex reindex --force      # rebuild even when fingerprints match
 memex remember "We use JWT in httpOnly cookies" --tags auth,decision
 memex remember "Auth lives in the cookie middleware" --tags auth,bugfix --paths src/auth/
 memex remember "Strip locale from JWT" --replaces <uuid>
+echo "Fact with \"quotes\"" | memex remember - --tags convention   # read from stdin
 memex recall "how is auth handled?" -k 5
 memex recall "how is auth handled?" --tags-all auth,security --recency
 memex recall "how is auth handled?" --rank blended
 memex forget <uuid>
-memex serve                # stdio MCP server
+memex serve                # optional stdio MCP server
 ```
 
 Add `--json` to any command for machine-readable output. From a checkout:
@@ -164,7 +182,9 @@ make reindex
 make reindex FORCE=1
 ```
 
-## MCP tools
+## MCP tools (optional)
+
+`memex serve` exposes the same operations as MCP tools:
 
 | Tool | Purpose |
 |------|---------|
@@ -203,11 +223,13 @@ verify important notes against the repository.
 In any git repository where agents should use Memex, install for your platform(s):
 
 ```bash
+memex install agents           # AGENTS.md only — any harness
 memex install cursor
 memex install claude
 memex install codex
-memex install all              # cursor + claude + codex
+memex install all              # agents + cursor + claude + codex
 memex install cursor claude    # multiple targets
+memex install all --mcp        # also write MCP server configs
 ```
 
 Every target is idempotent and always:
@@ -221,27 +243,31 @@ Platform extras:
 
 | Target | Also writes |
 |--------|-------------|
-| `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/` |
-| `claude` | `CLAUDE.md`, `.mcp.json` (`command: memex`, `MEMEX_ROOT=${CLAUDE_PROJECT_DIR:-.}`) |
-| `codex` | `.codex/config.toml` MCP block (`command: memex`, absolute `MEMEX_ROOT`) |
+| `agents` | nothing else |
+| `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}`) |
+| `claude` | `CLAUDE.md`; with `--mcp`: `.mcp.json` (`command: memex`, `MEMEX_ROOT=${CLAUDE_PROJECT_DIR:-.}`) |
+| `codex` | with `--mcp`: `.codex/config.toml` MCP block (`command: memex`, absolute `MEMEX_ROOT`) |
 
 Re-run after upgrading `git-memex` to refresh prompts from packaged templates.
-Flags: `--no-agents`, `--no-instructions`, `--no-rules`, `--no-mcp`,
-`--no-skills`, `--no-gitattributes`, `--command /path/to/memex`.
+Flags: `--mcp`, `--no-agents`, `--no-instructions`, `--no-rules`,
+`--no-skills`, `--no-gitattributes`, `--command /path/to/memex` (MCP binary).
+Re-running without `--mcp` never removes MCP config written earlier.
 
 Templates live in the package (`src/memex/templates/`). `AGENTS.md` is the
-canonical agent prompt; the Cursor `.mdc` is a short always-on pointer at that
+canonical agent prompt and tells agents to use the `memex` CLI (and
+`memex llms` for the full reference); `src/memex/templates/llms.txt` is that
+reference. The Cursor `.mdc` is a short always-on pointer at that
 block (Claude gets the same block in `CLAUDE.md`). Cursor skills live
 under `templates/skills/` and are copied into the target repo's
 `.cursor/skills/` (today: `memex-hygiene` to audit stale/stacked notes;
 user-invoked only). The agent files tell agents to
-**`recall` (MUST) before non-trivial / unfamiliar work, when debugging, and
+**`memex recall` (MUST) before non-trivial / unfamiliar work, when debugging, and
 when choices depend on project or business rules**, with sample queries and
-skip criteria for trivial edits, and to **`remember` durable decisions,
+skip criteria for trivial edits, and to **`memex remember` durable decisions,
 project/business rules, and solved problems** (symptoms → cause → fix).
-If a new fact supersedes an old note, agents should pass `replaces=<id>` (or
-`forget` the old id) rather than stacking a second memory. `list` catalogs
-what is stored; do not dummy-`recall` with a large `k`.
+If a new fact supersedes an old note, agents should pass `--replaces <id>` (or
+`memex forget` the old id) rather than stacking a second memory. `memex list`
+catalogs what is stored; do not dummy-recall with a large `-k`.
 
 ## Environment
 
@@ -258,7 +284,7 @@ what is stored; do not dummy-`recall` with a large `k`.
 |---------|-----|
 | `command not found: python` | Use `python3` (common on Linux/WSL) |
 | `command not found: memex` | Activate the venv, use `.venv/bin/memex`, or install globally (`uv tool install git-memex` / `pipx install git-memex`) |
-| `spawn … memex ENOENT` | Wrong or missing binary — default is `${userHome}/.local/bin/memex`; override with `--command` or install via `uv tool install git-memex` |
+| `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` |
 | `not a git repository` | Open a git checkout, or set `MEMEX_ROOT` to the repo root |
 | `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` |
 | `MODEL.json pins … but embedder is …` | Same model for the whole team, or `memex reindex --force` after intentional model change |

{git_memex-0.3.3 → git_memex-0.4.0}/src/git_memex.egg-info/SOURCES.txt

@@ -26,6 +26,7 @@ src/memex/store.py
 src/memex/tools.py
 src/memex/vectors.py
 src/memex/templates/AGENTS.md
+src/memex/templates/llms.txt
 src/memex/templates/memex.mdc
 src/memex/templates/skills/memex-hygiene/SKILL.md
 tests/test_cli.py

git_memex-0.4.0/src/memex/__init__.py

@@ -0,0 +1,3 @@
+"""Memex — repo-local vector memory for AI agents (CLI + optional MCP)."""
+
+__version__ = "0.4.0"