{"owner":"NevaMind-AI","repo":"memU","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\nOperational guide for AI coding agents working in this repository.\n\n## Mission\n\nShip small, verified feature and bugfix changes while preserving memU's current architecture.\n\nCore invariants:\n\n- `MemoryService` (`src/memu/app/service.py`) is the composition root: config, storage, and the embedding client pool. Its public surface is exactly the three `AgenticMixin` entry points — `list_all_recall_files`, `progressive_retrieve`, `commit_results`.\n- memU is embedding-only. No LLM/chat call happens anywhere in the service; do not add one.\n- Storage is pluggable across `inmemory`, `sqlite`, and `postgres`; repository contract changes require backend parity.\n- Scope data comes from `UserConfig.model`; validate `where` filters (`_normalize_where`) and do not bypass scope filtering.\n- Retrieval config lives in `ProgressiveRetrieveConfig` (`file` + `resource` layers); embedding profiles in `EmbeddingProfilesConfig`.\n\n## Layer Map\n\n- Service + three entry points: `src/memu/app/service.py`, `src/memu/app/agentic.py`\n- Config models/defaults: `src/memu/app/settings.py`\n- Storage protocols/factory: `src/memu/database/interfaces.py`, `src/memu/database/factory.py`\n- Backends: `src/memu/database/{inmemory,sqlite,postgres}/*`\n- Vector math/ranking: `src/memu/vector.py`\n- Embedding clients: `src/memu/embedding/*`\n- CLI (`memu`): `src/memu/cli.py`; shared `MEMU_*` config: `src/memu/env.py`\n- Host adapters (`memu-codex`, bridging pipeline): `src/memu/hosts/*`\n- Tests: `tests/*`\n\nRead the relevant implementation and nearby tests first. Prefer local patterns over new abstractions.\n\n## Implementation Rules\n\n- Keep changes narrow and localized to the affected layer.\n- Preserve async behavior and result shapes unless the task explicitly asks for a breaking change.\n- Maintain type hints and mypy compatibility.\n- Keep provider-specific logic inside `memu.embedding.backends`; storage-neutral logic outside concrete backends.\n- Do not duplicate client caching — use the existing `ClientPool` pattern.\n- Do not silently swallow errors that should be visible to callers or tests.\n\n## Backend Parity\n\nIf a repository method, model field, filter behavior, or vector search contract changes:\n\n1. Update the protocol in `src/memu/database/repositories/`.\n2. Update `inmemory`, `sqlite`, and `postgres` implementations where applicable.\n3. Extend `tests/test_agentic.py` (runs against inmemory + sqlite).\n4. Check migrations/bootstrap behavior for SQL backends (`src/memu/database/postgres/migrations/`).\n\n## Testing And Validation\n\nUse `uv` for local runs.\n\n- Setup: `make install`\n- Run all tests: `make test`\n- Run focused tests: `uv run python -m pytest tests/<target_test>.py`\n- Full quality checks: `make check`\n\nUseful focused areas:\n\n- The three entry points end-to-end: `tests/test_agentic.py`\n- Vector ranking: `tests/test_vector.py`\n- Embedding providers/gateway: `tests/test_embedding.py`\n- CLI surface: `tests/test_cli.py`\n- Host adapter inject seam: `tests/test_host_instruction.py`\n\n## Documentation Rules\n\n- Update `README.md` or `npm/README.md` when user-visible behavior changes.\n- Add or update ADRs under `docs/adr/` for architectural changes; existing ADRs are historical records — do not rewrite them.\n- Do not document speculative features as implemented.\n\n## Done Criteria\n\n- Code compiles for touched paths; tests for changed behavior pass.\n- New behavior has test coverage.\n- Backend parity considered and implemented where needed.\n- No unrelated files modified.\n"},"files":{"AGENTS.md":"# AGENTS.md\n\nOperational guide for AI coding agents working in this repository.\n\n## Mission\n\nShip small, verified feature and bugfix changes while preserving memU's current architecture.\n\nCore invariants:\n\n- `MemoryService` (`src/memu/app/service.py`) is the composition root: config, storage, and the embedding client pool. Its public surface is exactly the three `AgenticMixin` entry points — `list_all_recall_files`, `progressive_retrieve`, `commit_results`.\n- memU is embedding-only. No LLM/chat call happens anywhere in the service; do not add one.\n- Storage is pluggable across `inmemory`, `sqlite`, and `postgres`; repository contract changes require backend parity.\n- Scope data comes from `UserConfig.model`; validate `where` filters (`_normalize_where`) and do not bypass scope filtering.\n- Retrieval config lives in `ProgressiveRetrieveConfig` (`file` + `resource` layers); embedding profiles in `EmbeddingProfilesConfig`.\n\n## Layer Map\n\n- Service + three entry points: `src/memu/app/service.py`, `src/memu/app/agentic.py`\n- Config models/defaults: `src/memu/app/settings.py`\n- Storage protocols/factory: `src/memu/database/interfaces.py`, `src/memu/database/factory.py`\n- Backends: `src/memu/database/{inmemory,sqlite,postgres}/*`\n- Vector math/ranking: `src/memu/vector.py`\n- Embedding clients: `src/memu/embedding/*`\n- CLI (`memu`): `src/memu/cli.py`; shared `MEMU_*` config: `src/memu/env.py`\n- Host adapters (`memu-codex`, bridging pipeline): `src/memu/hosts/*`\n- Tests: `tests/*`\n\nRead the relevant implementation and nearby tests first. Prefer local patterns over new abstractions.\n\n## Implementation Rules\n\n- Keep changes narrow and localized to the affected layer.\n- Preserve async behavior and result shapes unless the task explicitly asks for a breaking change.\n- Maintain type hints and mypy compatibility.\n- Keep provider-specific logic inside `memu.embedding.backends`; storage-neutral logic outside concrete backends.\n- Do not duplicate client caching — use the existing `ClientPool` pattern.\n- Do not silently swallow errors that should be visible to callers or tests.\n\n## Backend Parity\n\nIf a repository method, model field, filter behavior, or vector search contract changes:\n\n1. Update the protocol in `src/memu/database/repositories/`.\n2. Update `inmemory`, `sqlite`, and `postgres` implementations where applicable.\n3. Extend `tests/test_agentic.py` (runs against inmemory + sqlite).\n4. Check migrations/bootstrap behavior for SQL backends (`src/memu/database/postgres/migrations/`).\n\n## Testing And Validation\n\nUse `uv` for local runs.\n\n- Setup: `make install`\n- Run all tests: `make test`\n- Run focused tests: `uv run python -m pytest tests/<target_test>.py`\n- Full quality checks: `make check`\n\nUseful focused areas:\n\n- The three entry points end-to-end: `tests/test_agentic.py`\n- Vector ranking: `tests/test_vector.py`\n- Embedding providers/gateway: `tests/test_embedding.py`\n- CLI surface: `tests/test_cli.py`\n- Host adapter inject seam: `tests/test_host_instruction.py`\n\n## Documentation Rules\n\n- Update `README.md` or `npm/README.md` when user-visible behavior changes.\n- Add or update ADRs under `docs/adr/` for architectural changes; existing ADRs are historical records — do not rewrite them.\n- Do not document speculative features as implemented.\n\n## Done Criteria\n\n- Code compiles for touched paths; tests for changed behavior pass.\n- New behavior has test coverage.\n- Backend parity considered and implemented where needed.\n- No unrelated files modified.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\nOperational guide for AI coding agents working in this repository.\n\n## Mission\n\nShip small, verified feature and bugfix changes while preserving memU's current architecture.\n\nCore invariants:\n\n- `MemoryService` (`src/memu/app/service.py`) is the composition root: config, storage, and the embedding client pool. Its public surface is exactly the three `AgenticMixin` entry points — `list_all_recall_files`, `progressive_retrieve`, `commit_results`.\n- memU is embedding-only. No LLM/chat call happens anywhere in the service; do not add one.\n- Storage is pluggable across `inmemory`, `sqlite`, and `postgres`; repository contract changes require backend parity.\n- Scope data comes from `UserConfig.model`; validate `where` filters (`_normalize_where`) and do not bypass scope filtering.\n- Retrieval config lives in `ProgressiveRetrieveConfig` (`file` + `resource` layers); embedding profiles in `EmbeddingProfilesConfig`.\n\n## Layer Map\n\n- Service + three entry points: `src/memu/app/service.py`, `src/memu/app/agentic.py`\n- Config models/defaults: `src/memu/app/settings.py`\n- Storage protocols/factory: `src/memu/database/interfaces.py`, `src/memu/database/factory.py`\n- Backends: `src/memu/database/{inmemory,sqlite,postgres}/*`\n- Vector math/ranking: `src/memu/vector.py`\n- Embedding clients: `src/memu/embedding/*`\n- CLI (`memu`): `src/memu/cli.py`; shared `MEMU_*` config: `src/memu/env.py`\n- Host adapters (`memu-codex`, bridging pipeline): `src/memu/hosts/*`\n- Tests: `tests/*`\n\nRead the relevant implementation and nearby tests first. Prefer local patterns over new abstractions.\n\n## Implementation Rules\n\n- Keep changes narrow and localized to the affected layer.\n- Preserve async behavior and result shapes unless the task explicitly asks for a breaking change.\n- Maintain type hints and mypy compatibility.\n- Keep provider-specific logic inside `memu.embedding.backends`; storage-neutral logic outside concrete backends.\n- Do not duplicate client caching — use the existing `ClientPool` pattern.\n- Do not silently swallow errors that should be visible to callers or tests.\n\n## Backend Parity\n\nIf a repository method, model field, filter behavior, or vector search contract changes:\n\n1. Update the protocol in `src/memu/database/repositories/`.\n2. Update `inmemory`, `sqlite`, and `postgres` implementations where applicable.\n3. Extend `tests/test_agentic.py` (runs against inmemory + sqlite).\n4. Check migrations/bootstrap behavior for SQL backends (`src/memu/database/postgres/migrations/`).\n\n## Testing And Validation\n\nUse `uv` for local runs.\n\n- Setup: `make install`\n- Run all tests: `make test`\n- Run focused tests: `uv run python -m pytest tests/<target_test>.py`\n- Full quality checks: `make check`\n\nUseful focused areas:\n\n- The three entry points end-to-end: `tests/test_agentic.py`\n- Vector ranking: `tests/test_vector.py`\n- Embedding providers/gateway: `tests/test_embedding.py`\n- CLI surface: `tests/test_cli.py`\n- Host adapter inject seam: `tests/test_host_instruction.py`\n\n## Documentation Rules\n\n- Update `README.md` or `npm/README.md` when user-visible behavior changes.\n- Add or update ADRs under `docs/adr/` for architectural changes; existing ADRs are historical records — do not rewrite them.\n- Do not document speculative features as implemented.\n\n## Done Criteria\n\n- Code compiles for touched paths; tests for changed behavior pass.\n- New behavior has test coverage.\n- Backend parity considered and implemented where needed.\n- No unrelated files modified.\n","category":"root","tokens":875}]}