docs: README depth pass - describe the whole project (EN + RU) - #3
AndrewMoryakov wants to merge 2 commits into
Conversation
…d advanced users (EN + RU)
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c52868095d
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - Connect your AI clients: `agentmemory connect-clients`, then `agentmemory status-clients --compact` ([Client wiring](#client-wiring)). | ||
| - Look at what was stored in the browser console ([Browser UI](#browser-ui); from source it needs a one-time `npm install && npm run build` in `web/`). | ||
| - Run the MCP self-test: `agentmemory mcp-smoke`. |
There was a problem hiding this comment.
On a fresh checkout following either quick-start block, the package is installed only into .venv and the environment is never activated, so the bare agentmemory connect-clients, status-clients, and mcp-smoke commands here fail with command-not-found. Use the platform-specific .venv executable paths shown above or add an activation step before these next steps.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 79bbf4d. Confirmed: pyproject [project.scripts] installs agentmemory only into .venv, and neither quick-start block activates it, so the bare commands in "Next steps" were not on PATH. Added an activation / explicit-path note ahead of the Next steps list, a matching note under the header teaser, and extended the "agentmemory not found" troubleshooting entry (README.md and README.ru.md).
|
|
||
| ### Claude Memory (experimental) | ||
|
|
||
| `claude_memory` is a conservative file-backed adapter over Claude Code memory surfaces: it can read user-level memory, project memory and auto-memory (each switchable with `--no-user-memory` / `--no-auto-memory`), and writes only into an AgentMemory-owned directory (by default `.claude/rules/agentmemory` under the project's Git root). It declares no update, no delete and no scope inventory. |
There was a problem hiding this comment.
When a user selects claude_memory and applies both documented flags expecting the listed sources to be switchable, project memory is still always scanned: _discover_sources() unconditionally reads project CLAUDE.md, .claude/CLAUDE.md, and .claude/rules/**/*.md, while the two flags gate only user-level and auto-memory sources. This can make project content searchable despite the documented expectation, so either remove “each switchable” or add an actual project-memory disable option.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 79bbf4d. Confirmed: ClaudeMemoryProvider._discover_sources() (agentmemory/providers/claude_memory.py) always scans project CLAUDE.md / CLAUDE.local.md walk-up, .claude/CLAUDE.md and .claude/rules/**/*.md; only include_user_memory and include_auto_memory (--no-user-memory / --no-auto-memory) gate sources. The Claude Memory section now says project memory is always read with no opt-out and only user-level and auto memory are switchable (EN + RU).
| | `POST /mcp` | MCP over HTTP (JSON-RPC, single or batch) | | ||
| | `/.well-known/oauth-authorization-server`, `/.well-known/oauth-protected-resource`, `/oauth/authorize`, `/oauth/token`, `/register` | OAuth 2.1 and Dynamic Client Registration | | ||
|
|
||
| Without a configured token and without OAuth, the API is open (intended for local-only use). With `AGENTMEMORY_API_TOKEN` or OAuth enabled, everything except `/health`, the discovery documents and the OAuth authorize/token/register endpoints requires a bearer credential. Error responses use typed `error_type` values mapped to HTTP statuses. |
There was a problem hiding this comment.
With an API token or static OAuth configured, this blanket statement is false for the browser assets: Handler.do_GET serves /, /me, /assets/*, and root SPA assets before calling _require_auth(). The data requests remain protected, but operators relying on this security description may assume the entire UI is inaccessible; document the public static routes or narrow the claim to API/data routes and point remote deployments to AGENTMEMORY_DISABLE_UI=1.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 79bbf4d. Confirmed: Handler.do_GET in agentmemory/api.py serves SPA_ROUTES (/, /me), /assets/* and SPA_ROOT_ASSETS before any _require_auth() call; /admin/* and the other data routes are guarded afterwards. The HTTP API auth paragraph now lists the unauthenticated static routes (and that /health returns only {"ok": true} to unauthenticated callers) and points remote deployments to AGENTMEMORY_DISABLE_UI=1; the Guards bullet and the Browser UI section carry the same caveat (EN + RU).
- Quick start next steps: bare `agentmemory` commands only work from the activated .venv; add activation / explicit-path note (header teaser, Next steps, troubleshooting), EN + RU. - claude_memory: project memory (CLAUDE.md walk-up, .claude/CLAUDE.md, .claude/rules/**) is always read; only user-level and auto memory are switchable. EN + RU. - Auth rule: the browser UI's static routes (/, /me, /assets/*, root files) are served without a credential; narrow the "everything requires a bearer" claim and point remote deployments to AGENTMEMORY_DISABLE_UI=1. HTTP API, Guards, Browser UI sections, EN + RU.
1 participant
README depth pass for the whole project (EN + RU), no code changes.
The previous front-page README (merged in #2) was short and told the "shared runtime over CLI/HTTP/MCP" story; many subsystems were barely visible. This rework keeps the header, both images, the review-fixed quick start and every old section, and layers the page:
npm install && npm run buildinweb/when run from source (otherwise/returns 503); the old text implied it was just served.Everything is taken from code and docs in the repo (operation registry, provider metadata, api.py routes, CHANGELOG, backlog). Planned/proposed items are labelled as such. English first, Russian is a full translation.