jzjzzzzzzz/agent-me

Agent‑Me – an open‑source “AI twin” of yourself

What it is – Agent‑Me is a runnable FastAPI + React application that lets you turn a collection of personal knowledge (stored as version‑controlled Markdown) into a small, inspectable AI agent. The agent does not just regurgitate facts; it follows a deterministic, multi‑stage pipeline – retrieval → planning → research → critique → writing → optional verification – and returns the full trace of what happened.

Why it matters – Most personal chatbots are a single prompt plus a vector store. Agent‑Me treats a personal AI as a system with explicit memory, provenance, and evidence‑grounded answers. All intermediate steps are exposed, making it possible to see why the twin says something and to block synthesis when evidence is missing.

---

Core concepts

Component	Role	Implementation (as described in the README)
Personal knowledge	The twin’s static body of facts, preferences, experiences, etc.	Reviewable, version‑controlled Markdown files (e.g., knowledge/example-profile.md).
RAG	Finds relevant excerpts before answering.	A bounded, deterministic local retriever that works over the Markdown corpus.
Planner	Decides the overall approach to a question.	Produces a typed Plan dataclass.
Researcher	Pulls the exact source excerpts needed for the plan.	Returns an EvidenceBundle with excerpts and metadata.
Critic	Checks whether the evidence is sufficient for synthesis.	Emits a Critique; can block the pipeline with an “insufficient‑evidence” response.
Writer	Generates the final answer, citing the evidence.	Emits a WrittenAnswer that includes citations and a safe summary.
Verifier (optional)	Runs extra checks on citation paths and other invariants.	Produces a Verification result; can reject the answer if checks fail.
Public trace	Makes the whole execution observable.	JSON payload containing each stage’s outcome, safe summary, and metrics.
Evaluation	Guarantees deterministic behavior for regression testing.	Versioned fixtures (course/fixtures/...) and a deterministic evaluator run in CI.

---

How it works (high‑level flow)

1. User sends a request to /api/v1/collaborate (or the chat endpoint). The request includes the question and the desired workflow (default = Planner‑Researcher‑Critic‑Writer, verified = adds Verifier).
2. Retrieval pulls relevant Markdown excerpts from the local corpus.
3. Planner creates a structured plan describing what needs to be answered.
4. Researcher gathers the exact excerpts required by the plan.
5. Critic validates that the gathered evidence is sufficient; if not, it returns a fixed “insufficient‑evidence” reply.
6. Writer composes a citation‑aware answer.
7. Verifier (when enabled) checks citation paths and other invariants; failures are blocked.
8. Response includes the answer, the list of sources, a grounded flag, and a full trace of each stage.

---

Getting started (quick‑start)

Method	Steps
Docker Compose (recommended)	1️⃣ git clone https://github.com/jzjzzzzzzz/agent-me.git 2️⃣ cd agent-me && cp .env.example .env 3️⃣ docker compose up --build Access UI at http://localhost:5173 and API docs at http://localhost:8000/docs.
Local toolchain	Requires Python 3.11+, uv, Node 22+, npm. Run make setup then start the backend (uvicorn …) and frontend (npm run dev).
Optional LLM provider	Set LLM_BASE_URL, LLM_API_KEY, and LLM_MODEL in .env to point at an OpenAI‑compatible endpoint (e.g., OrcaRouter). Only the /api/v1/chat endpoint uses the external model; /collaborate stays fully local.

---

Typical use cases

• Personal knowledge assistant – ask the twin questions about your own projects, preferences, or past decisions and receive answers that cite the exact markdown entry they came from.
• Research reproducibility – the public trace lets you audit how a conclusion was reached, which is useful for compliance or academic settings.
• Educational demo – the repository includes a bilingual curriculum that walks developers through building the pipeline step‑by‑step.
• Prototype for a continuously learning AI twin – the architecture is deliberately modular so you can replace the markdown store with a richer graph, add consent‑based ingestion, or plug in tool‑calling modules.

---

Limitations (as stated in the repo)

• Memory is currently a static set of Markdown files; no automatic ingestion or forgetting.
• Structured identity models, temporal reasoning, and confidence scores are future work.
• The Verifier only checks citation‑path invariants; it does not guarantee factual truth.
• When using an external LLM provider, only the chat endpoint sends data outside; the core collaboration pipeline remains local.
• The system is an experimental architecture, not a production‑ready personal assistant.

---

Where to look next

• Architecture details – docs/ARCHITECTURE.md
• API schema – docs/API.md
• Trust model – docs/TRUST.md
• Roadmap & contribution – ROADMAP.md and CONTRIBUTING.md
• Evaluation fixtures – course/fixtures/collaboration_cases.json

---

Bottom line – Agent‑Me is a concrete, open‑source platform for building an “AI twin” that stores personal knowledge in an inspectable form and answers questions through a transparent, multi‑agent pipeline. It is deliberately bounded (local retrieval, deterministic runs) but designed to be extended toward a continuously learning, privacy‑preserving digital representation of a person.