Agent-Me / open source architecture
DEEP DIVE
17 SEP 2026

Build a digital
representation
that can explain itself.

An inspectable AI Agent Twin for exploring how personal knowledge can become a grounded, reviewable system.

VISIBLE SYSTEM PATH01 / 05
reviewable memory↓
retrieval + evidence↓
roles + critique↓
verification → answer↗

Source: Agent-Me repository. This deck is an independent explainer based on the public source available on 17 September 2026.

01 / Plain-English TL;DR

It’s not a chatbot with a biography.

Agent-Me is a small, open-source system that tries to make an AI representation of a person explainable, evidence-grounded and correctable.

The useful idea is the middle layer: what happens between personal memory and the final answer.
01

Give it reviewed knowledge

Its current public memory substrate is version-controlled Markdown, not an invisible profile.

02

Make the work visible

Retrieval, planning, evidence, critique and verification become inspectable stages.

03

Keep the boundary honest

The project labels what is implemented, what is optional and what remains future work.

Source: README / What is Agent-Me?

02 / Why it matters

A personal AI needs more than recall.

The project frames an AI Twin as a system that should answer five uncomfortable questions.

What do you know?

Keep the knowledge substrate explicit and reviewable.

Where did it come from?

Keep evidence tied to exact source excerpts.

How certain is it?

Leave room for uncertainty, gaps and blocked synthesis.

Can I correct it?

Owner control is part of the roadmap, not a cosmetic setting.

Plain-English benefit

When the AI’s reasoning path is visible as safe operational artefacts, you can debug the system instead of arguing with a polished answer.

What that buys you

More useful context, clearer failure modes, easier testing, and a better basis for deciding what the AI is allowed to do next.

Sources: README / Why an AI Twin? · Roadmap / Design principles

03 / Use cases

Useful anywhere context is expensive to rebuild.

The examples below are reasonable applications of the architecture, not claims that the current repository ships these finished products.

Founder / creator

Decision memory

Ask what you decided, why you decided it, and which source or trade-off supports that choice.

Researcher

Evidence-first notebook

Retrieve the right notes, show the excerpts, and block synthesis when the corpus doesn’t support the answer.

Product team

Project context layer

Give a team a shared, inspectable view of priorities, preferences, decisions and open questions.

Good fit

Personal or team knowledge that changes over time and needs provenance, review and correction.

Poor fit

A black-box “make it sound exactly like me” chatbot where the source, uncertainty and controls don’t matter.

Interpretation grounded in: README / Why an AI Twin? · Roadmap / Structured identity and memory

SECTION 02 / DEEP DIVE

The mechanism is inspectability.

The repository makes the middle of the system explicit: bounded retrieval, typed handoffs, role separation, safe traces and mechanical checks.

04 / Architecture

One system, two request paths.

A React browser sends typed requests to FastAPI. From there, Agent-Me can answer through a single retrieval path or run the sequential collaboration workflow.

Both collaboration policies run in one process against the same bounded retriever.

Source: docs/ARCHITECTURE.md · docs/API.md

05 / Deep dive

Five roles, each with one job.

The point isn’t to maximise the number of agents. It’s to make important decisions explicit and testable.

01

Planner

Normalises the question and creates the retrieval plan.

02

Researcher

Runs retrieval and packages exact excerpts as evidence.

03

Critic

Blocks synthesis when the evidence bundle is empty.

04

Writer

Creates a citation-aware answer artefact.

05

Verifier

Checks mechanical output invariants in verified mode.

BaselinePlanner → Researcher → Critic → Writer
VerifiedBaseline + Verifier checks citation paths, citation counts and non-empty output

Sources: docs/ARCHITECTURE.md / Role-based workflow · docs/TRUST.md / What the verifier verifies

06 / Deep dive

The safest answer can be a block.

Agent-Me treats missing evidence as a system state, not an invitation to fill the gap with confidence.

Evidence bundle

  • Exact source excerpts
  • Source path and metadata
  • Bounded retrieval result
critic gate

Two possible paths

Evidence found
Writer synthesises and cites.
No evidence
Critic blocks. Writer returns a fixed insufficient-evidence response.
Important boundary

“Grounded” means the implemented retrieval and policy checks passed. It doesn’t prove factual truth, semantic entailment, source quality or completeness.

Source: docs/TRUST.md · docs/API.md / collaborate

07 / Deep dive

Inspect the handoffs, not hidden thought.

# frozen handoff artefacts
Plan(query, task_count)
EvidenceBundle(sources, excerpts)
Critique(approved, reason)
WrittenAnswer(answer, citations)
Verification(passed, checks)

The trace is an operational record that helps you understand what the workflow did.

01plannerexecution plan created3 tasks
02researcherevidence bundle collected4 sources
03criticevidence sufficiency checkedapproved
04writeranswer artefact produced2 cites

Agent-Me explicitly says the trace isn’t a model’s private chain-of-thought. It contains safe stage summaries, outcomes and metrics.

Source: docs/ARCHITECTURE.md · docs/API.md / response trace

08 / Trust boundary

Local-first by default. Provider mode is a deliberate boundary.

Local extractive + collaboration modes

  • No external model provider required.
  • Questions, excerpts and traces stay local to the app’s process.
  • Reads reviewed Markdown beneath the configured knowledge root.
  • No paid model API is required for the default workflow.

Optional provider mode

  • Only the single-path chat route uses the provider today.
  • The question, recent history and retrieved context cross the configured provider boundary.
  • Provider retention, training and regional terms sit outside this repository’s control.
  • Review the trust documentation before adding private knowledge.
owner control → reviewed knowledge · explicit provider choice · safe text rendering · documented limits

Source: docs/TRUST.md / Local modes · Provider mode

09 / Evaluation

Measure behaviour beyond a good conversation.

4/4

The repository’s default collaboration evaluator reports all four checked-in cases passed.

Supported requestfixture
Unsupported requestfixture
Adversarial requestfixture
Boundary requestfixture
Read the number correctly

This is deterministic evaluation for the same code, corpus, workflow and input. It’s useful regression evidence, not proof that the system is factually correct in the wild.

Source: README / Evaluation · course/fixtures/collaboration_cases.json

10 / Boundaries

The ambition is larger than the current implementation.

Now

Reviewable Markdown, bounded deterministic retrieval, typed roles, evidence gates, safe traces and deterministic fixtures.

Next

Structured identity and memory with people, projects, preferences, decisions, timestamps and provenance.

Now

Five-stage verification checks citation paths, counts and non-empty output.

Not yet

It doesn’t prove truth, semantic entailment, source quality, freshness or absence of contradictions.

Now

Reference implementation runs in-process and sequentially.

Future

Continuous learning with consent, review, deduplication, conflict handling, forgetting and recovery.

Current foundation

  • inspectable retrieval
  • typed orchestration
  • owner-visible evidence

Longer-term test

  • what changed?
  • what’s uncertain?
  • can I correct or delete it?

Source: ROADMAP.md / Current foundation · What success looks like

SECTION 03 / HOW-TO GUIDE

Start bounded.
Earn agency later.

The safest implementation path begins with a small corpus, local execution, explicit contracts and repeatable evaluation.

11 / How to implement

Get a working local baseline in three moves.

1

Clone and configure

Copy the example environment, then start the Compose stack.

git clone
cp .env.example .env
2

Run the reference app

Open the web app and inspect the API, health and readiness endpoints.

docker compose
up --build
3

Try the verified workflow

Ask a question through the collaboration endpoint and inspect the trace.

POST /api/v1/
collaborate
Web

localhost:5173

API docs

localhost:8000/docs

Readiness

localhost:8000/ready

Source: README / Quick start

12 / How to implement

Replace the demo identity with reviewed knowledge.

Your first product decision is not the model. It’s the memory contract.
1
Choose the corpus

Start with Markdown you’re allowed to use and willing to review.

2
Name the boundaries

Separate public examples from private identity and memory.

3
Keep source paths

Every useful personal claim should retain where it came from.

4
Expose correction

Design review, correction, export and deletion before continuous ingestion.

# minimal reviewed memory
claim: "Prefers evidence before action"
source: "decision-log/2026-04.md"
learned_at: "2026-04-18"
confidence: "reviewed"
sensitivity: "private"
owner_control: "correct | export | delete"

The example above is illustrative schema thinking for implementation. It isn’t a claimed current Agent-Me file format.

Source: README / Build your own AI Twin · ROADMAP.md / Structured identity and memory

13 / How to implement

Every new capability needs a boundary and a test.

1

Add a case before adding behaviour

Include supported, unsupported, adversarial and boundary requests.

course/fixtures/
2

Keep Python and TypeScript contracts aligned

Extend typed artefacts together so the browser rejects malformed responses safely.

backend/app/
frontend/src/
3

Make provider choice explicit

Only cross the provider boundary when its data-processing terms are acceptable.

.env
/ready
4

Run quality gates before sharing

Test, evaluate, validate docs and inspect the public trace.

make lint test
make evaluate
Implementation rule of thumb

If you can’t say what the new stage receives, returns, exposes, stores and how it fails, it’s not ready to become part of the Twin.

Source: README / Build your own AI Twin · ROADMAP.md / How to contribute

14 / How to implement

A practical path from memory to agency.

Stage 1

Recall

Retrieve reviewed facts and source excerpts.

Stage 2

Explain

Show the plan, evidence, critique and answer.

Stage 3

Learn

Accept candidate memories through review and provenance.

Stage 4

Act

Add bounded tools with permissions, approvals and rollback.

The sequence matters: inspectability before autonomy.

That’s the strategic lesson of Agent-Me. Make the system understandable while its scope is still small enough to change.

Interpretation grounded in: ROADMAP.md / workstreams

15 / Closing

The goal isn’t to make a chatbot sound like you.

It’s to explore what it takes to build a digital representation that can increasingly think with your context, while staying attributable, uncertain when appropriate, private, correctable and inspectable.

Remember

Memory without provenance is just a confident cache.

Build next

Start with one corpus, one workflow, one evaluation set and one owner-visible trace.

Primary source: github.com/jzjzzzzzzz/agent-me · Key reading: Architecture · Trust · Roadmap

01 / 18