{"id":51856277,"url":"https://github.com/ellmos-ai/build-your-users-mind","last_synced_at":"2026-07-24T01:03:47.868Z","repository":{"id":365349174,"uuid":"1271665421","full_name":"ellmos-ai/build-your-users-mind","owner":"ellmos-ai","description":"A recipe for any AI agent to build a self-improving theory-of-mind model of its user from interaction logs (feedback precognition). What you mind is what you get.","archived":false,"fork":false,"pushed_at":"2026-07-21T23:04:53.000Z","size":432,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-07-21T23:05:52.324Z","etag":null,"topics":["agent-memory","ai-agents","claude-code","codex-cli","decision-support","feedback","gemini-cli","llm","llm-agents","llm-memory","local-first","personalization","prompt-analysis","prompt-archaeology","theory-of-mind","user-modeling"],"latest_commit_sha":null,"homepage":"https://github.com/ellmos-ai/build-your-users-mind#readme","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ellmos-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"custom":["https://paypal.me/lukasgeiger2507"]}},"created_at":"2026-06-16T22:30:08.000Z","updated_at":"2026-07-21T23:04:57.000Z","dependencies_parsed_at":"2026-07-21T23:01:52.276Z","dependency_job_id":null,"html_url":"https://github.com/ellmos-ai/build-your-users-mind","commit_stats":null,"previous_names":["ellmos-ai/build-your-users-mind"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ellmos-ai/build-your-users-mind","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ellmos-ai%2Fbuild-your-users-mind","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ellmos-ai%2Fbuild-your-users-mind/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ellmos-ai%2Fbuild-your-users-mind/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ellmos-ai%2Fbuild-your-users-mind/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ellmos-ai","download_url":"https://codeload.github.com/ellmos-ai/build-your-users-mind/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ellmos-ai%2Fbuild-your-users-mind/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35822076,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-23T02:00:06.683Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","ai-agents","claude-code","codex-cli","decision-support","feedback","gemini-cli","llm","llm-agents","llm-memory","local-first","personalization","prompt-analysis","prompt-archaeology","theory-of-mind","user-modeling"],"created_at":"2026-07-24T01:03:47.071Z","updated_at":"2026-07-24T01:03:47.851Z","avatar_url":"https://github.com/ellmos-ai.png","language":"Python","funding_links":["https://paypal.me/lukasgeiger2507"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\u003cimg src=\"assets/banner.svg\" alt=\"build-your-users-mind — what you mind is what you get\" width=\"100%\"\u003e\u003c/p\u003e\n\n# build-your-users-mind\n\n\u003e **What you mind is what you get.**\n\n**🌐 [EN](README.md) · [DE](locales/de/README.md) · [ES](locales/es/README.md) · [JA](locales/ja/README.md) · [RU](locales/ru/README.md) · [ZH](locales/zh/README.md)** — English is authoritative; translations may lag.\n\nA local-first recipe for an operator to build an empirical, inspectable **preference and\ndecision-support model** from their own AI interaction logs. It can help an authorized agent\nanticipate feedback in recurring situations; it does not reveal a person's mind and must not be\nused for psychological diagnosis, covert profiling, or high-stakes autonomous decisions.\n\nIt works by **feedforward**: the agent makes an explicitly uncertain feedback prediction, uses it\nonly inside the operator's authorization boundary, and later evaluates it against real feedback.\nNovel, external, irreversible, or high-impact actions always require confirmation.\n\n**Status:** `1.1.0-dev` — public development release. The deterministic safety and classification\ncontracts are tested on Windows and Linux; semantic model quality still requires human review.\n\n## \"I know what you want.\"\n\nThe agent reads authorized logs, distils **what the user explicitly decided, how they phrased it,\nand whether later feedback offered a weak outcome signal**, and turns it into a small set of living,\neditable documents. These are hypotheses with citations, not facts about an inner mental state.\n\nIt is **not** a chatbot persona and **not** a heavy framework — it is a method + a handful of scripts\n+ document templates. The only agent-specific part is the *source adapter* (where each agent reads its\nown logs). Everything else is universal.\n\n## Try it in 60 seconds\n\nRun the deterministic preparation/validation pipeline and feedback scorer **offline** on synthetic\ndata — no LLM, no API key, no network:\n\n```bash\ngit clone https://github.com/ellmos-ai/build-your-users-mind\ncd build-your-users-mind\npython examples/synthetic-demo/run_demo.py\n```\n\nYou'll watch `extract → merge → chunk → classify → validate → aggregate → score feedback` run on a\nfictional user's logs and pre-authored loop fixtures (a planted secret gets redacted), then the hard\nvalidation gate reject a tampered result with a non-zero exit. The fixtures demonstrate mechanics,\nnot accuracy. Details: [`examples/synthetic-demo/`](examples/synthetic-demo/).\n\n[![build-your-users-mind — 2:28 demo](https://img.youtube.com/vi/oJlrCHW-BXQ/maxresdefault.jpg)](https://youtu.be/oJlrCHW-BXQ)\n\n🎬 **Watch the 2:28 demo:** https://youtu.be/oJlrCHW-BXQ\n\n## Built with OpenAI Codex\n\n- The **Codex source adapter** (`scripts/adapters/codex_adapter.py`) — the component that reads\n  Codex's own session logs — **was written by Codex itself** in Codex Session\n  `019ed298-fdc4-72d2-a255-97d7dc117128` (commit `1e3abc4`, *\"Add Codex source adapter (delegated\n  to Codex, control-tested)\"*), then control-tested on 946 real prompts. This earlier contribution\n  is intentionally attributed to Codex without claiming a specific model version.\n- **Codex also authored this repository's discovery metadata** — commit `0ec49df` carries the git\n  author `Codex \u003ccodex@local\u003e`. It's all in the git history.\n- **GPT-5.6 powered the final Build Week hardening pass through Codex** (Codex Session\n  `019f8674-fe9a-7d91-a80f-7ee799e8ced0`). It found and fixed nine privacy and data-integrity\n  defects across source extraction, redaction, corpus merging, and prediction scoring; the final\n  deterministic suite contains 73 tests.\n- Codex is a first-class **source**: what Codex learns about the user flows into the same shared,\n  evidence-cited model that all agents consume (see `SOURCE-ADAPTERS.md`).\n\n## Start here\n\n| If you are... | Open first | Why |\n|---|---|---|\n| An AI agent adding user-memory discipline | `SKILL.md` | End-to-end implementation recipe |\n| A maintainer wiring log sources | `SOURCE-ADAPTERS.md` | Claude, Codex, Gemini/agy and Kimi log locations |\n| A reviewer checking safety boundaries | `SECURITY.md` and `.gitignore` | Redaction, private-corpus and generated-avatar exclusions |\n| A researcher comparing concepts | `TAXONOMY.md` | Prompt-Archaeology categories and decision patterns |\n\n## Find this repository\n\nCanonical search phrase: **`ellmos-ai/build-your-users-mind`**.\n\nUseful discovery phrases:\n- `AI agent theory of mind user model`\n- `LLM user modeling from interaction logs`\n- `Codex Claude Gemini Kimi source adapters`\n- `prompt archaeology feedback precognition`\n- `local-first AI personalization templates`\n- `agent memory decision support from prompt logs`\n\nDisambiguation: this is not a SaaS personalization product, HR platform, chatbot persona pack,\ngeneral prompt library or psychological diagnosis tool. It is a local-first documentation and script\nkit for building an evidence-backed user model from private agent interaction logs.\n\n## How it works — feedback precognition\n\nA 0→4 runtime loop (see `templates/START.md`):\n\n| Step | File | Role |\n|---|---|---|\n| 0 | project `DECISIONS.md` | project-specific decisions win (more specific) |\n| 1 | `WHAT-\u003cUSER\u003e-SAID` | **evidence-based** rules/decisions (with prompt-ID citations) |\n| 2 | `WHAT-WOULD-\u003cUSER\u003e-SAY` | **precognition** — predicted feedback + confidence (🟢/🟡/🔴) |\n| 3 | `WHAT-I-DID…` + `MY-ACTIONS.txt` | log of actions taken on the prediction |\n| 4 | `WHAT-\u003cUSER\u003e-SAID-ABOUT…` | **evaluation** — prediction vs. reality → improves (1) and (2) |\n\nQuality metric = **how often the anticipated reaction matches the user's real later feedback.**\nAt 🔴 (novel/no pattern) the rule is **escalate, don't guess.**\nMeasure it from the loop files with\n[`scripts/score_predictions.py`](scripts/score_predictions.py): hit rate overall and per\n🟢/🟡/🔴 tier, plus the 🔴 escalation rate.\n\n### Pipeline (build the model)\n1. **Extract** (`scripts/corpus_extract.py`) — deterministic: pull only human-typed prompts from your\n   logs, filter synthetic turns, **redact secrets**, link each prompt to the next turn's `outcome_signal`\n   (praise/correction/reissue/none).\n2. **Merge** (`scripts/merge_corpora.py`) — combine source-specific outputs without overwriting or\n   renumbering stable evidence IDs.\n3. **Chunk** (`scripts/chunk_corpus.py`) — dedupe, optional domains, and build a fresh manifest bound\n   to the exact corpus SHA-256.\n4. **Classify** — use `templates/CLASSIFY-CHUNK.md` and `schemas/classification.schema.json`, then run\n   `scripts/validate_classifications.py`. Missing rows, malformed output, stale files, and ID\n   collisions are hard failures.\n5. **Aggregate** (`scripts/aggregate_stats.py`) — type distribution, B:K ratio, turning points.\n6. **Author** the avatar files from `templates/` and **bind** a short pointer into the agent's own\n   memory/rules file (Claude `CLAUDE.md`, Codex `GPT.md`/`AGENTS.md`, Gemini `GEMINI.md`, …).\n\nSee `SKILL.md` for the full recipe and `SOURCE-ADAPTERS.md` for per-agent log locations.\n\n## Theory of us — theoretical background\n\nThe system models the **dyad** (agent ↔ user), not just the user in isolation — a *theory of us*.\nIt is grounded in:\n- **Theory of Mind** research for LLM agents — predicting and conditioning on an interlocutor's mental\n  state improves outcomes (e.g. *ToM-SWE*, arXiv 2510.21903; *Infusing Theory of Mind into Socially\n  Intelligent LLM Agents*, 2509.22887; *Persistent Memory \u0026 User Profiles*, 2510.07925).\n- **Prompt-Archaeology** (L. Geiger) — the method of classifying full human-AI interaction protocols,\n  whose 8-type taxonomy this module reuses (`TAXONOMY.md`).\n- A known limit: LLM ToM is **robust on recurring cases, fragile under novel/adversarial variation** —\n  hence the confidence tiers and the \"escalate, don't guess\" rule.\n\n## Bias \u0026 limits (read before trusting it)\n- **Silent approval is invisible** — users type corrections, not praise → the model over-represents\n  corrections and skews \"critical\". Calibrate accordingly.\n- **Evidence IDs are deterministic, but evidence claims and labels are synthesized** — resolve\n  load-bearing IDs against the raw corpus and review the inference.\n- **Classifier bias** — spot-check a sample; report inter-rater agreement for serious use.\n\n## Privacy \u0026 redaction\nUse only logs the operator is authorized to process. Extractors fail closed on missing roots,\ninvalid dates, unreadable/empty inputs, and missing timestamps; an empty replacement requires\nexplicit `--allow-empty`, while accepting malformed partial input requires `--allow-partial`.\nWrites are atomic and private where the platform supports permissions.\nBuilt-in rules cover common current tokens (including modern project-scoped API tokens), credentials, asymmetric credential material,\nemails, IP-like values, and long digit runs. Domain-specific health, legal, tax, financial, or other\nsensitive content cannot be inferred reliably: provide reviewed `--redaction-rules` before writing\nor sharing. Never commit a real corpus or filled avatar file — see `.gitignore`.\n\n## Suggested GitHub topics\n`theory-of-mind` · `llm` · `user-modeling` · `personalization` · `ai-agents` · `prompt-analysis`\n· `feedback` · `decision-support`\n\n## Credits \u0026 License\nMethod: *Prompt-Archaeology* by Lukas Geiger. Module \u0026 concept: Lukas Geiger (+ Claude).\nBundled dependency: `swarm-operations` skill. **MIT** — see `LICENSE`.\nReference implementation (private, not shipped): a personal instance built on the author's own logs.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fellmos-ai%2Fbuild-your-users-mind","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fellmos-ai%2Fbuild-your-users-mind","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fellmos-ai%2Fbuild-your-users-mind/lists"}