AlexandrAI AGENTS.md
agents-md

Personal Work Agent Memory and Document Pipeline Agent Guide

Project-specific AGENTS.md guidance for Personal Work Agent file memory, document pipeline, chat pipeline, topic continuity, prompting, and tests.

AGENTS.md

Guidance for coding agents working on Personal Work Agent memory and document-processing services.

Project Overview

The memory and document boundary stores file memory, processes documents, composes chat pipeline behavior, applies topic-continuity decisions, and builds source-aware system prompts. It supports retrieval-style behavior without mixing it into connector clients or runtime composition.

Use this boundary when changing memory storage, document conversion, chat pipeline policy, continuity scoring, or prompt text.

Project Map

  • src/workagent/services/file_memory.py provides FileMemoryStore.
  • src/workagent/services/document_pipeline.py defines DocumentPipeline.
  • src/workagent/services/chat_pipeline.py defines ChatPipeline.
  • src/workagent/services/topic_continuity.py decides whether new input continues a topic.
  • src/workagent/services/prompting.py contains source-specific system prompt text.
  • docs/operations/mvp2-memory-repair.md and docs/operations/mvp2-embedding-spike.md document operational context.
  • tests/test_memory_foundation.py, test_memory_policy.py, test_document_pipeline.py, test_chat_pipeline.py, test_topic_continuity.py, and retrieval tests cover behavior.

Setup Commands

bashuv run pytest tests/test_memory_foundation.py tests/test_memory_policy.py tests/test_document_pipeline.py -q
uv run pytest tests/test_chat_pipeline.py tests/test_topic_continuity.py tests/test_prompting.py -q
uv run pytest tests/test_retrieval_relevance.py tests/test_sqlite_vec_store_optimization.py -q
make lint

Change Rules For Agents

  • Keep memory persistence and retrieval behavior separated from platform connector clients.
  • Treat document content as untrusted user data.
  • Keep prompt changes narrow and source-specific.
  • Add tests for topic-continuity thresholds or time-window behavior.
  • Do not store raw credentials, private local paths, or hidden environment values in memory records.
  • Keep retrieval tests focused on relevance and filtering, not only data presence.
  • Update operation docs when memory behavior changes materially.

Verification

bashuv run pytest tests/test_memory_foundation.py tests/test_document_pipeline.py tests/test_chat_pipeline.py -q
make lint

Run retrieval and embedding tests for vector or relevance changes.

Security Notes

Memory records may include sensitive user documents. Keep access local, avoid public path leakage, and redact secrets in logs and generated summaries.

PR Checklist

  • Prompt changes are source-scoped.
  • Topic continuity tests cover edge cases.
  • Memory writes avoid secrets and local absolute paths.
  • Retrieval behavior is verified beyond simple count checks.