Agent-Me

Distill yourself into an AI Agent Twin.

Feed it your knowledge, memories, projects, preferences, experiences, and decisions. Agent-Me turns them into an AI Agent Twin that keeps learning how you think and work.

It is not just a chatbot that knows facts about you. It is an open-source, inspectable architecture for building a second digital version of you—one that can retrieve, reason, verify, and eventually act with your context.

An AI agent that is learning to become me.

Quick start · Roadmap · Architecture · Learn · Contribute

English · 简体中文 · All languages

What is Agent-Me?

A conventional chatbot starts over with a prompt and returns an answer:

user → prompt → model → answer

Agent-Me treats a personal AI as a system:

your knowledge
      ↓
reviewable memory → retrieval → planning → evidence → critique → verification → response

The aim is not merely to answer questions about a person. It is to build an increasingly useful AI representation of:

• what I know;
• what I have done;
• what I prefer;
• how I make decisions;
• what evidence supports those beliefs; and
• how certain the system should be about them.

Today, the repository provides a runnable FastAPI + React implementation over reviewable Markdown knowledge, with deterministic retrieval and sequential agent roles. The public repository uses fictional examples; each owner keeps their real identity and memory in a separate private workspace.

Why an AI Twin?

Many personal chatbots are effectively a prompt, a vector database, and a chat interface. They can recall biographical facts or imitate a writing style, but that is not the same as reliably representing a person.

Remembering facts about a person is easy. Building a system that can reliably represent that person is much harder.

The deeper question behind Agent-Me is: what would it take for an AI to actually represent a person? Such a system needs more than recall. It needs durable identity and memory models, provenance, temporal updates, uncertainty, reasoning, verification, and user control.

Agent-Me does not claim to solve all of those problems today. It provides a concrete, testable architecture for exploring them without hiding the process behind a single model response.

Why Agent-Me is different

Reviewable identity and memory

The current memory substrate is version-controlled Markdown: small, explicit, and inspectable. It gives the twin a stable body of personal knowledge instead of treating every conversation as isolated. An optional private workspace adds SQLite-backed profile entries, persisted chat transcripts, and user-confirmed memories. Automatic temporal reasoning and richer identity models remain future work.

Evidence-grounded responses

Retrieved personal knowledge remains connected to exact source excerpts. The system can refuse synthesis when it has insufficient evidence rather than filling gaps with confident invention.

Multi-agent reasoning

Planner, Researcher, Critic, Writer, and optional Verifier roles have separate responsibilities and communicate through typed Python contracts. The goal is not to maximize the number of agents; it is to make important decisions explicit and testable.

Inspectable execution

Agent-Me exposes a public execution trace: role outcomes, safe intermediate summaries, evidence, metrics, retrieval activity, and verification results. It does not expose or claim to expose a model's private chain-of-thought.

Verification and evaluation

Before an answer is returned, implemented checks can validate citation paths, evidence policy, and output invariants. Versioned cases then test supported, unsupported, adversarial, and boundary requests deterministically.

Most AI assistants show you only:

prompt → answer

Agent-Me exposes the system in between:

memory → retrieval → planning → evidence → critique → verification → answer

Because if an AI is going to represent you, you should be able to inspect why it speaks for you.

How it works

Knowledge graphs, richer structured memory, typed intent routing, and broader tool calling are natural extensions of this model, but are not presented here as finished capabilities.

Architecture

Agent-Me treats an AI Twin as a system, not a prompt.

flowchart LR
  Browser[React UI] -->|typed request| API[FastAPI request guard]
  API --> Chat[Single-path Q&A]
  API --> Flow[Sequential role orchestrator]
  Chat --> Search[Deterministic retrieval]
  Flow --> P[Planner]
  P -->|Plan| R[Researcher]
  R --> Search
  Search --> Docs[(Reviewable personal knowledge)]
  R -->|EvidenceBundle| C[Critic]
  C -->|Critique| W[Writer]
  W -. verified policy .-> V[Verifier]
  W --> Result[Answer + sources + public trace]
  V --> Result
  Chat -. optional provider mode .-> Provider[OpenAI-compatible provider]
  Cases[(Versioned cases)] --> Eval[Deterministic evaluator]
  Eval --> CI[GitHub Actions]

The baseline policy executes Planner → Researcher → Critic → Writer. The verified policy adds Verifier as a fifth stage. Frozen dataclasses define the Plan, EvidenceBundle, Critique, WrittenAnswer, and Verification handoffs. Both policies run sequentially in one process against the same bounded retriever.

[!NOTE] The Verifier checks citation paths and other implemented output invariants. It does not prove factual truth or semantic entailment. See Trust, Data Flow, and Deployment Boundaries for the complete system boundary.

Read System Architecture for request paths and contracts, and API Reference for endpoint schemas.

Inspect a run

Run the five-stage verified workflow:

curl http://localhost:8000/api/v1/collaborate \
  -H 'Content-Type: application/json' \
  -d '{"question":"How does the example agent plan a project?","workflow":"verified"}'

When evidence is missing, the Critic blocks synthesis and the Writer returns a fixed insufficient-evidence response. In verified mode, invalid citation paths or citation-count metadata are blocked as well.

Evaluation

The checked-in fixtures cover supported, unsupported, adversarial, and boundary requests. Results are deterministic for the same code, corpus, workflow, and input.

make test
make evaluate
.venv/bin/python scripts/evaluate_collaboration.py --workflow verified --json

The default evaluator reports COLLABORATION_EVAL 4/4 passed. CI also runs backend tests, frontend lint/typecheck/tests/build, documentation validation, both workflow policies, and container smoke tests. See Lesson 06 and the evaluation fixtures.

Quick start

Docker Compose

Requirement: Docker with the Compose plugin.

git clone https://github.com/jzjzzzzzzz/agent-me.git
cd agent-me
cp .env.example .env
docker compose up --build

The default configuration uses local extractive and collaboration modes, so no API key is required. The web container reaches the API through a same-origin /api gateway.

Optional OrcaRouter provider

Agent-Me's provider path uses the OpenAI-compatible Chat Completions API, so it can connect to OrcaRouter without a provider-specific SDK. Create an OrcaRouter API key, then set the following values in your private .env:

LLM_BASE_URL=https://api.orcarouter.ai/v1
LLM_API_KEY=sk-orca-YOUR_KEY
LLM_MODEL=orcarouter/auto

Restart the API and check `/rea