agent-memory-git 0.1.0__py3-none-any.whl

agent_memory/webui/index.html

@@ -0,0 +1,31 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Memories</title>
+<link rel="stylesheet" href="/app.css">
+</head>
+<body>
+<header class="top">
+  <div class="bar">
+    <div class="search">
+      <svg class="search-ico" viewBox="0 0 16 16" aria-hidden="true"><circle cx="7" cy="7" r="4.8"/><path d="m10.6 10.6 3.4 3.4"/></svg>
+      <input id="q" type="search" placeholder="Search memories" autocomplete="off" spellcheck="false" aria-label="Search memories">
+      <kbd>/</kbd>
+    </div>
+    <span class="sync" id="sync" hidden></span>
+    <button class="btn primary" id="new" title="New memory (n)">New</button>
+  </div>
+  <div class="filters" id="filters"></div>
+</header>
+
+<main class="list" id="list" aria-label="Memories"></main>
+<div class="selbar" id="selbar" hidden></div>
+
+<aside class="drawer" id="drawer" aria-hidden="true"></aside>
+<div class="toasts" id="toasts" aria-live="polite"></div>
+<div class="boot" id="boot">Loading memories…</div>
+<script src="/app.js"></script>
+</body>
+</html>

agent_memory/workdir.py

@@ -0,0 +1,135 @@
+"""Finding the real project folder behind a throwaway session folder.
+
+Claude Code sessions started without a folder run in a scratch workspace, and
+the Codex desktop app creates a fresh folder per thread. A `here` memory
+recorded there would never match a later session, so we look at the session
+transcript and attribute the memory to the folder the session worked in most.
+"""
+
+import json
+import os
+import re
+from pathlib import Path
+
+from . import config
+from .util import HOME, is_under
+
+DEFAULT_THROWAWAY = [
+    r"/scratch-workspaces/",                          # Claude Code, no folder chosen
+    r"^~/Documents/Codex/\d{4}-\d{2}-\d{2}/[^/]+",    # Codex desktop, one folder per thread
+]
+# Folders that only hold other folders; never the answer on their own.
+CONTAINERS = re.compile(r"^(Library/CloudStorage(/[^/]+)?|Library/Application Support|"
+                        r"Library/Mobile Documents|Documents|Documents/Codex|"
+                        r"Documents/Codex/\d{4}-\d{2}-\d{2}|Desktop|Downloads)$")
+TAIL_BYTES = 8 * 1024 * 1024  # new memories are about recent work
+MIN_HITS = 3
+DESCEND_SHARE = 0.6
+MAX_DEPTH = 4  # levels below home; a git root always ends the descent
+
+
+def _patterns(home):
+    pats = config.load().get("throwaway_patterns") or DEFAULT_THROWAWAY
+    return [re.compile(p.replace("^~", "^" + re.escape(str(home)), 1)) for p in pats]
+
+
+def is_throwaway(path, home=None):
+    return bool(path) and any(p.search(path) for p in _patterns(home or HOME))
+
+
+# Under ~/Library only synced document folders can hold projects.
+LIBRARY_PROJECT_ROOTS = ("CloudStorage", "Mobile Documents")
+
+
+def _evidence(line):
+    """True for transcript lines that show what the session did.
+
+    Instructions and injected context (AGENTS.md, CLAUDE.md, memory summaries,
+    hook output) mention many unrelated folders, so only tool calls, tool
+    results and the conversation itself count.
+    """
+    try:
+        d = json.loads(line)
+    except ValueError:
+        return False
+    kind = d.get("type")
+    if kind == "response_item":  # Codex rollout
+        payload = d.get("payload") or {}
+        return payload.get("type") != "message" or payload.get("role") == "assistant"
+    return kind in ("user", "assistant")  # Claude Code transcript
+
+
+def _read_evidence(path):
+    try:
+        size = os.path.getsize(path)
+        with open(path, "rb") as f:
+            if size > TAIL_BYTES:
+                f.seek(size - TAIL_BYTES)
+            raw = f.read().decode("utf-8", "replace")
+    except (OSError, TypeError):
+        return ""
+    return "\n".join(line for line in raw.splitlines() if _evidence(line))
+
+
+def infer(transcript, cwd=None, exclude=(), home=None):
+    """The project folder a transcript refers to most, or None.
+
+    Counts every folder prefix (two to five levels below home) of the absolute
+    paths in the transcript, starts from the most referenced top-level folder,
+    and descends while one child holds most of the references, stopping at a
+    git checkout root.
+    """
+    home = Path(home or HOME)
+    text = _read_evidence(transcript) if transcript else ""
+    if not text:
+        return None
+    path_re = re.compile(re.escape(str(home)) + r"(?:/[^\s\"'\\`<>|;:,()\[\]{}*?]+)+")
+    counts = {}
+    for m in path_re.finditer(text):
+        parts = Path(m.group(0).rstrip(".")).relative_to(home).parts
+        if len(parts) < 2 or parts[0].startswith("."):
+            continue
+        if parts[0] == "Library" and parts[1] not in LIBRARY_PROJECT_ROOTS:
+            continue
+        for depth in range(2, min(len(parts), 5) + 1):
+            key = parts[:depth]
+            counts[key] = counts.get(key, 0) + 1
+
+    blocked = [str(Path(e)) for e in exclude if e]
+
+    def usable(key):
+        p = str(home.joinpath(*key))
+        if not os.path.isdir(p) or is_throwaway(p, home):
+            return False
+        if cwd and (p == cwd or is_under(cwd, p)):
+            return False
+        return not any(p == b or is_under(p, b) for b in blocked)
+
+    def descend(n, best):
+        limit = MAX_DEPTH + (2 if best[0] == "Library" else 0)  # ~/Library/CloudStorage/<drive>/...
+        while len(best) < limit and not home.joinpath(*best, ".git").exists():
+            kids = [(c, k) for k, c in counts.items()
+                    if len(k) == len(best) + 1 and k[:len(best)] == best and usable(k)]
+            if not kids:
+                break
+            c, k = max(kids)
+            if c < DESCEND_SHARE * n and not CONTAINERS.match("/".join(best)):
+                break
+            n, best = c, k
+        return None if CONTAINERS.match("/".join(best)) else best
+
+    # Most referenced first; a container that leads nowhere (e.g. ~/Documents/Codex, whose
+    # children are all throwaway threads) gives way to the next candidate.
+    top = sorted(((n, k) for k, n in counts.items() if len(k) == 2 and usable(k)), reverse=True)
+    for n, key in top:
+        if n < MIN_HITS:
+            break
+        best = descend(n, key)
+        if best:
+            return str(home.joinpath(*best))
+    return None
+
+
+def default_exclude():
+    data = config.data_dir()
+    return [str(config.CODE_DIR)] + ([str(data)] if data else [])

agent_memory_git-0.1.0.dist-info/METADATA

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: agent-memory-git
+Version: 0.1.0
+Summary: Shared, git-backed memory for Claude Code and Codex.
+Keywords: claude-code,codex,memory,agents,git
+Author: Shichao Song
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Dist: numpy>=2.0 ; extra == 'ui'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/Ki-Seki/agent-memory
+Project-URL: Repository, https://github.com/Ki-Seki/agent-memory
+Project-URL: Demo, https://github.com/Ki-Seki/agent-memory-data-demo
+Provides-Extra: ui
+Description-Content-Type: text/markdown
+
+# agent-memory
+
+One memory for Claude Code and Codex, kept as plain Markdown files in a git repository you own.
+
+When a session starts, a hook gives the agent an index of the memories that matter where it is
+running: everything marked global, plus what was learned in the same folder or repository. When
+a turn ends, a hook commits what the agent wrote, with full provenance (tool, session, host,
+folder, git remote), and pushes it. Both tools read and write the same files, so a preference
+you gave Codex is there the next time Claude Code starts, on any machine that pulls the data
+repository. This repository holds only the code; the memories live in a separate data
+repository.
+
+![mem ui listing memories, with one open on the right](docs/mem-ui.png)
+
+<sub>`mem ui` on the [demo data repository](https://github.com/Ki-Seki/agent-memory-data-demo).</sub>
+
+## Try it without installing
+
+```bash
+git clone https://github.com/Ki-Seki/agent-memory
+git clone https://github.com/Ki-Seki/agent-memory-data-demo
+cd agent-memory
+AGENT_MEMORY_DATA=../agent-memory-data-demo bin/mem ui --keywords-only
+```
+
+`AGENT_MEMORY_DATA` points `mem` at the demo repository, so nothing is installed and no hooks
+change. The page needs `numpy`. `--keywords-only` skips the optional embedding model; leave it
+out after `mem ui --fetch-model` to also search by meaning.
+
+## How it works
+
+- **One file per memory.** Frontmatter carries `type` (user / feedback / project / reference),
+  `scope` (global / here), a one-line `description`, and provenance under `source`: tool, session
+  id and name, model, host, folder, git root, remote, branch and commit. Files live in
+  `memories/YYYY/MM/<id>.md`; the folders exist only to keep listings short.
+- **Session start.** A SessionStart hook works out where the session runs (folder, host, git
+  identity), picks every `global` memory plus the `here` memories recorded at the same place,
+  and injects a compact index (under 10,000 characters, the Claude Code hook limit).
+- **Writing.** The agent writes new memories into a per-session staging folder and edits existing
+  files in place. At the end of each turn a Stop hook stamps ids and provenance, moves staged
+  files into `memories/`, commits, and pushes in the background. The agent never writes
+  provenance itself.
+- **Rules.** [`PROTOCOL.md`](src/agent_memory/PROTOCOL.md) tells the agent what to save and how.
+  `mem install` copies it to `~/.config/agent-memory/PROTOCOL.md`, which `~/.claude/CLAUDE.md`
+  imports, and into `~/.codex/AGENTS.md` for Codex.
+
+Sessions in throwaway folders (Claude Code scratch workspaces, Codex per-thread folders under
+`~/Documents/Codex/<date>/`) get their `here` memories filed under the project folder the
+transcript shows them working in most, with the original folder kept as `source.original_cwd`.
+`mem relocate` applies the same inference to existing memories. Patterns can be overridden with
+`throwaway_patterns` in `~/.config/agent-memory/config.json`.
+
+A `here` memory matches a session when they share the folder (100), the git checkout (90), the
+remote (80, other clones and worktrees), or when one folder contains the other (70 / 60). Home
+and its direct children such as `~/repos` are too broad to match through containment.
+
+## Setup
+
+Requires Python 3.11+, git and [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv tool install "agent-memory-git[ui]"     # the mem command; [ui] adds numpy for mem ui
+mem init ~/repos/agent-memory-data     # create the data repository and ~/.config/agent-memory
+mem import claude --dry-run            # preview, then run without --dry-run
+mem import codex --dry-run
+mem install --dry-run                  # shows every change as a diff
+mem install
+```
+
+To upgrade, run `uv tool upgrade agent-memory-git` and then `mem install`, which refreshes the
+protocol copies; `mem doctor` says when they are out of date.
+
+`install` edits, and records in `~/.config/agent-memory/install-state.json`:
+
+| File | Change |
+|---|---|
+| `~/.claude/settings.json` | SessionStart / Stop / SessionEnd hooks, `autoMemoryEnabled: false`, read/edit permission on the data repository, `mem search/list/show` allowed |
+| `~/.claude/CLAUDE.md` | a marked block importing `~/.config/agent-memory/PROTOCOL.md`, a copy of the protocol |
+| `~/.codex/hooks.json` | the same three hooks |
+| `~/.codex/config.toml` | `memories.generate_memories = false`, `memories.use_memories = false`, data repository added to `sandbox_workspace_write.writable_roots` |
+| `~/.codex/AGENTS.md` | a marked block with the protocol |
+| `~/.local/bin/mem` | symlink to `mem`, only if that file does not exist yet (`uv tool install` already puts one there) |
+
+Codex asks you to trust new hooks once: open `/hooks` in Codex and enable the three
+agent-memory hooks.
+
+`mem uninstall` reverts exactly those edits (other changes the tools made in the meantime are
+kept) and turns native memory back on. The data repository is never touched by uninstall.
+
+## Commands
+
+```
+mem index [--cwd DIR]           what a session started here would see
+mem list [--global|--here|--all] [--type T]
+mem search WORDS... [--all]     full-text search; --all includes other locations
+mem show ID|NAME|PATH
+mem add --name N --type T --scope S --description D BODY|-
+mem flush                       commit anything left in staging
+mem relocate [PATH...] [--dry-run]  re-file memories recorded in throwaway folders
+mem sync [--pull-only]          pull --rebase and push the data repository
+mem lint [ID...] [--summary]    list memories that do not follow the body format
+mem ui [--port N] [--no-open]   search, filter, read and edit memories in a local page
+mem doctor                      check the installation
+```
+
+## Managing memories in a page
+
+`mem ui` starts a small server on `127.0.0.1` and opens a page listing every memory. Keep the
+terminal open while you use it. It needs `numpy`; the hooks do not.
+
+- **Find.** One search box (press `/`). Word matches appear as you type, with the matching words
+  marked; a moment later the local model adds memories close in meaning, across Chinese and
+  English. Filters narrow the list by type, where a memory loads (everywhere, or one project or
+  folder), which tool wrote it, keyword, age, and whether it needs tidying (what `mem lint`
+  reports, also listed on the open memory); the order is newest, oldest, recently changed or A to Z.
+- **Read.** Click a row, or move with `j`/`k` and press Enter. The memory opens on the right with
+  every frontmatter field (including each `source` entry), the body rendered as Markdown with
+  `[[links]]` that open other memories, the file exactly as stored, and the most similar memories.
+- **Change.** Edit (`e`) or delete from the open memory, add one with New (`n`), or tick several
+  rows (`x`) and delete them together. Every change is one git commit, pushed in the background,
+  with Undo. If an agent edits the same file meanwhile, saving is refused rather than overwriting.
+
+Similar memories and search by meaning use Qwen3-Embedding-0.6B, int8 ONNX, on the CPU, in a
+separate `uv run --with onnxruntime --with tokenizers` environment; vectors are cached by content
+in `<data>/.cache/embeddings/`. Get the model once with `mem ui --fetch-model` (about 625 MB,
+pinned revision, checked by SHA-256). Without it, or with `--keywords-only`, similar memories
+come from keyword vectors and search matches words only.
+
+Keywords are the words that most set a memory apart from the others (TF-IDF). Words that should
+never be keywords, such as your own name, go in `keyword_stopwords` in
+`~/.config/agent-memory/config.json`.
+
+The server only listens on loopback, and every request needs the one-time token from the link it
+prints, so other web pages cannot read or change memories.
+
+## Development
+
+```bash
+uv sync --all-extras          # dev tools and numpy
+uv run pytest
+uv run ruff check .
+```
+
+From a checkout, `bin/mem` (or `uv run mem`) runs the code in place; `mem install` from there
+points the hooks at that checkout, so edits take effect in the next session.
+`uv tool install --editable .` does the same with `mem` on PATH.
+
+To release, run `uv run scripts/release.py prepare patch` (or `minor`, `major`) to open a
+version PR. After it is merged, `uv run scripts/release.py publish <PR_NUMBER>` creates the GitHub
+Release, and GitHub Actions publishes it to PyPI.
+
+## Notes
+
+- Hooks never fail the host session; errors go to `<data>/.cache/agent-memory.log`.
+- Git operations are serialized with a lock file, so parallel sessions are safe on one machine.
+  Across machines, unique file names keep merge conflicts rare; a failed rebase is aborted and
+  logged for you to resolve.
+- Session names come from Claude Code's `custom-title` transcript entries and Codex's thread
+  database, when available.
+
+## License
+
+[MIT](LICENSE)

agent_memory_git-0.1.0.dist-info/RECORD

@@ -0,0 +1,29 @@
+agent_memory/PROTOCOL.md,sha256=hIcQuU7_5pnZsRCQe6qwbIAM8oelkEqJDlJbRBKrKAI,5561
+agent_memory/__init__.py,sha256=olPmw2ADtt5kRXBMCbzecXyclqRAzVJj1xDp14-i1gw,59
+agent_memory/__main__.py,sha256=_gX5kpLNLWRafVMqXZG1H759ZYvqzfFQWm06dydxGVQ,108
+agent_memory/capture.py,sha256=4hxKgcjv0BAqaBh8NcWu3EyXTlsO-Mzp3o79k-V8eCo,7295
+agent_memory/cli.py,sha256=rZZ-PhaNckZJwzH8Fs-amuGTSRAPT8_in1vGbVMyqkM,11622
+agent_memory/config.py,sha256=VaffcaZ3Tv0q2DSXnoSSQFPg21U-LkFTdbjnVp2J95M,1744
+agent_memory/context.py,sha256=7qN2J6y78he06o1qnDIHsCOryVTmtv8vAlnkIJm2lRM,2239
+agent_memory/embed_worker.py,sha256=Dxt2r3RgQGz1qCBQXylTTPr12DpMUaHowPlsVLleH0s,3656
+agent_memory/frontmatter.py,sha256=L3MV9liCEcZet_F2rfYiDjowslqas4Qdq49XNrGi_xw,4081
+agent_memory/gitsync.py,sha256=7RCuNTTp8t5bZUOJTrCorEt-x50LwrzKDaOIrIoZVYs,4318
+agent_memory/hooks.py,sha256=sAJVfBYTAeRV499GTAfwEJvxoqAioVcq0yPibRKORf4,3151
+agent_memory/importers.py,sha256=OELhZWMpJbC0vSSaFW2nQsH0pnV9B9_PAEo3t9FkOVA,10030
+agent_memory/install.py,sha256=z9FHVdH3ERTG7CcBL5bNVXtkkVBiuajkfwx9Xw1Zcpg,19353
+agent_memory/lint.py,sha256=0sBNM1Si2vVx4C_gfiQyqBM84eFeFn396S4T01WwItI,1999
+agent_memory/select.py,sha256=rLVrxeB71HEGFzETU0TeN9NsKqSTO0KMGHRq4V3qnm4,3636
+agent_memory/sessions.py,sha256=GhKPn-JwjVWmunUp43-CyzT_UosSl-g8PgfOaIa7hDo,1906
+agent_memory/store.py,sha256=u0K6OS11aQYcklFQMcRDzPvv2B1nzJfrg8Yb3j1geOw,3134
+agent_memory/ui.py,sha256=XFQr7XwAOT8pSFKb20wwkuKCEtQzpW2gOBTBx3vsNII,19162
+agent_memory/ui_server.py,sha256=Oo1Bu38ri67eFG8Qxn9TY_V1wjn0Ru8YBnx0ba0XamY,16676
+agent_memory/util.py,sha256=AnrPFOkUuJc0pbx6l3R3YgzYmZCdehEGH-zTesjgHPI,2640
+agent_memory/webui/app.css,sha256=MFy6pVxSiP2yuA8lYtvcP_mO73SV8jbMCsC-Pau6Nx4,13996
+agent_memory/webui/app.js,sha256=Qv2Vcte9Rs4GOUxt97LYkcKnXu18rKrHBQNkjqD49zg,34863
+agent_memory/webui/index.html,sha256=LlOPxJ7_c0-mBmfGGi03H1dwPCFQEqk3DCG4GwX1GoU,1092
+agent_memory/workdir.py,sha256=rEhDu_8PceFtBNPsnxouKg6u7h4QH_EzMJJ53dqeckE,5175
+agent_memory_git-0.1.0.dist-info/licenses/LICENSE,sha256=paJRjXM3OSoEnxnAmj9GxNgOlnSYVoQKpRb9YsTeIN4,1069
+agent_memory_git-0.1.0.dist-info/WHEEL,sha256=-i9oRNYVXXZJUIYl5zclLIg6onEb0NLibTX34uln84w,81
+agent_memory_git-0.1.0.dist-info/entry_points.txt,sha256=26FMYMESWCr0b6i8W27V6emfz2sEPIYea5CXscSmQAQ,47
+agent_memory_git-0.1.0.dist-info/METADATA,sha256=OmRRaLqttn3U3k0akSzHN1Rl4ouXxnTKxH1GGgU4dVs,9540
+agent_memory_git-0.1.0.dist-info/RECORD,,

agent_memory_git-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.13
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_memory_git-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+mem = agent_memory.cli:main
+

agent_memory_git-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shichao Song
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.