{"id":50351204,"url":"https://github.com/marcomc/agent-learning-system","last_synced_at":"2026-05-29T21:01:38.403Z","repository":{"id":358867383,"uuid":"1243433192","full_name":"marcomc/agent-learning-system","owner":"marcomc","description":"Local Codex skills and automations for reusable agent learnings","archived":false,"fork":false,"pushed_at":"2026-05-29T11:05:52.000Z","size":24,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T13:06:06.429Z","etag":null,"topics":["agent-learning","ai-agent","automation","cli","codex","developer-tools","knowledge-management","markdown","obsidian","python","skills"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marcomc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-19T10:37:54.000Z","updated_at":"2026-05-29T11:05:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/marcomc/agent-learning-system","commit_stats":null,"previous_names":["marcomc/agent-learning-system"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/marcomc/agent-learning-system","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcomc%2Fagent-learning-system","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcomc%2Fagent-learning-system/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcomc%2Fagent-learning-system/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcomc%2Fagent-learning-system/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcomc","download_url":"https://codeload.github.com/marcomc/agent-learning-system/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcomc%2Fagent-learning-system/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33670211,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"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-learning","ai-agent","automation","cli","codex","developer-tools","knowledge-management","markdown","obsidian","python","skills"],"created_at":"2026-05-29T21:01:36.976Z","updated_at":"2026-05-29T21:01:38.389Z","avatar_url":"https://github.com/marcomc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Learning System\n\nLocal Codex skills and automations for capturing real debugging and review\nlearnings, storing them in a filesystem-backed Markdown tree, and promoting\nreusable lessons into agent instructions and review skills.\n\n## Table of Contents\n\n- [Purpose](#purpose)\n- [Repository Layout](#repository-layout)\n- [Install](#install)\n- [Learning Store](#learning-store)\n- [Skills](#skills)\n- [Review Skill Hooks](#review-skill-hooks)\n- [Automations](#automations)\n- [Validation](#validation)\n\n## Purpose\n\nThe system keeps learning lightweight and auditable:\n\n- session-level findings are recorded as Obsidian notes;\n- processed notes are kept as history, not deleted;\n- daily consolidation reads only new inbox notes and review decisions;\n- reusable lessons are promoted to the smallest useful target;\n- no repository is committed or pushed automatically.\n\n## Repository Layout\n\n```text\n.\n├── README.md\n├── CHANGELOG.md\n├── AGENTS.md\n├── config.example.env\n├── install.sh\n├── automations/\n│   ├── midnight-consolidation.md\n│   ├── morning-review-email.md\n│   └── noon-consolidation.md\n├── scripts/\n│   └── agent_learning.py\n├── skills/\n│   ├── consolidate-agent-learnings/\n│   └── record-agent-learning/\n└── tests/\n    └── test_agent_learning.py\n```\n\n## Install\n\nRun:\n\n```bash\n./install.sh\n```\n\nThe installer:\n\n- detects the active Obsidian vault as a convenient default filesystem path;\n- writes `~/.config/agent-learning-system/config.env`;\n- creates the learning store folders;\n- copies both skills into `~/.agents/skills`;\n- links `~/.codex/skills` to the installed `~/.agents/skills` copies;\n- installs or updates the three Codex automations as active;\n- validates Markdown, shell, and Python files.\n\nPass `--dir PATH` to choose any filesystem directory as the learning-store base.\nThe store itself is created as `PATH/AI Agent Learnings/`. If `PATH` is inside\nan Obsidian vault, Obsidian will show the Markdown notes automatically; no\nObsidian API or MCP server is required.\n\nPass `--skip-automations` if you only want to install config and skills. If the\nObsidian provider is `mcp-pending`, automation installation is skipped until\ndirect filesystem access or a working MCP setup is configured.\n\nPass `--email ADDRESS` before relying on the morning review email. Without it,\nthe installer records a reserved example address and the morning notification\nflow will not send mail.\n\nIf the default Obsidian vault is not found, the installer asks for a direct\nfilesystem directory path or records MCP mode as pending. Direct filesystem\naccess is the recommended mode for this project because the automation only\nneeds local Markdown files.\n\nThis setup flow follows `install.sh`, including validation, config creation,\nskill copy installation, Codex mirrors, automation records, and final local\nchecks.\n\n```mermaid\nflowchart LR\n  accTitle: Install setup flow\n  accDescr: Shows how install.sh resolves config, installs skills, and validates.\n  start[\"Run install.sh\"] --\u003e parse[\"Parse directory, email, and mode\"]\n  parse --\u003e validate[\"Run Markdown, shell, and Python checks\"]\n  validate --\u003e base{\"Base directory known?\"}\n  base --\u003e|Default or --dir| config[\"Write config.env\"]\n  base --\u003e|Prompt or fallback| pending[\"Record direct or MCP-pending mode\"]\n  pending --\u003e config\n  config --\u003e store[\"Initialize learning store\"]\n  store --\u003e install[\"Copy .agents skills\"]\n  install --\u003e mirror[\"Link .codex skill mirrors\"]\n  mirror --\u003e automations[\"Install active Codex automations\"]\n  automations --\u003e done[\"Finish install\"]\n```\n\n## Learning Store\n\nThe canonical archive lives under `AGENT_LEARNING_DIR` plus\n`AGENT_LEARNING_STORE_NAME`.\n\nExample:\n\n```env\nAGENT_LEARNING_DIR=\"/any/filesystem/folder\"\nAGENT_LEARNING_STORE_NAME=\"AI Agent Learnings\"\n```\n\nThis creates:\n\n```text\n/any/filesystem/folder/AI Agent Learnings/\n├── inbox/\n├── needs-review/\n├── processed/YYYY/MM/\n├── reports/\n└── state/\n    └── processed.json\n```\n\n`AGENT_LEARNING_DIR` may be any local filesystem directory. When it points at an\nObsidian vault, Obsidian sees the generated Markdown files as normal notes.\n\n\u003e Source: `scripts/agent_learning.py` commands `record`, `prepare-run`,\n\u003e `finalize-note`, and `write-report`.\n\n```mermaid\nflowchart LR\n  accTitle: Agent learning lifecycle\n  accDescr: Shows how learning notes move through Obsidian and promotion.\n  session[\"Session yields reusable lesson\"] --\u003e record[\"Run record command\"]\n  record --\u003e inbox[\"Write note to inbox\"]\n  inbox --\u003e prepare[\"Consolidator runs prepare-run\"]\n  prepare --\u003e classify{\"Clear reusable rule?\"}\n  classify --\u003e|Yes| promote[\"Promote to bounded targets\"]\n  classify --\u003e|No| review[\"Move to needs-review\"]\n  review --\u003e decide{\"One review box checked?\"}\n  decide --\u003e|No| wait[\"Leave note pending\"]\n  decide --\u003e|Yes| finalize[\"Process reviewed decision\"]\n  promote --\u003e archive[\"Archive processed note\"]\n  finalize --\u003e archive\n  archive --\u003e report[\"Write consolidation report\"]\n```\n\nReview notes contain a stable checkbox block:\n\n```markdown\n## Review Decision\n\n\u003c!-- BEGIN AGENT LEARNING REVIEW --\u003e\n- [ ] Approve: promote this rule\n- [ ] Retry: I edited the rule, reprocess it\n- [ ] Reject: do not promote this rule\n\u003c!-- END AGENT LEARNING REVIEW --\u003e\n```\n\nThe consolidator reads `inbox/`, `needs-review/`, and `state/processed.json`.\nIt does not reread `processed/` history unless resolving a duplicate or\nconflict.\n\n## Conflicts and precedence (visual)\n\n```mermaid\nflowchart LR\n  accTitle: Rule precedence when two rules disagree\n  accDescr: Shows which rule wins when guidance conflicts.\n  g[\"Global: $HOME/AGENTS.md\"] --\u003e p[\"Project: \u003crepo\u003e/AGENTS.md\"]\n  p --\u003e s[\"Domain skill: $HOME/.agents/skills/*/SKILL.md\"]\n  s --\u003e d{\"Same scope?\"}\n  d --\u003e|No| keep[\"Keep both; clarify scope\"]\n  d --\u003e|Yes| review[\"Send to needs-review\"]\n```\n\n## Conflict detection levels\n\n```mermaid\nflowchart LR\n  accTitle: Where conflicts should be detected\n  accDescr: Promotion-time and periodic audits.\n  capture[\"Capture note\"] --\u003e consolidate[\"Consolidate/promote\"]\n  consolidate --\u003e detect_now[\"Detect conflicts in touched targets\"]\n  detect_now --\u003e ok[\"Finalize processed\"]\n  detect_now --\u003e unsure[\"Move to needs-review\"]\n  consolidate --\u003e detect_daily[\"Daily audit (cleanup)\"]\n  detect_daily --\u003e review2[\"Open needs-review or fix targets\"]\n```\n\nThe system currently supports a periodic audit via `audit-rules` (see below).\n\n## Skills\n\n### `record-agent-learning`\n\nUse after a session produces a real reusable finding, fix, regression, or\nworkflow correction. It writes one structured note to `inbox/`.\n\nIt also has an explicit hook mode for user-requested setup. Hook mode scans the\nlocal skill directory for review-oriented skills and appends an idempotent\n`Agent Learning Hook` section to each detected target. It does not run during\nordinary one-off capture.\n\n### `consolidate-agent-learnings`\n\nUse from scheduled automation or manually when promoting learning notes. It\nclassifies new notes, handles reviewed checkbox decisions, promotes strong\nlessons, moves notes, writes reports, and validates changed files.\n\n### `audit-rules`\n\nScan promoted targets (default: `$HOME/AGENTS.md` and `$HOME/.agents/skills/**`)\nfor duplicate or potentially conflicting bullets.\n\n```bash\npython3 scripts/agent_learning.py audit-rules\n```\n\nLimit the scan to a specific directory or file:\n\n```bash\npython3 scripts/agent_learning.py audit-rules --path /path/to/dir-or-file\n```\n\n## Review Skill Hooks\n\nPreview detected review skills:\n\n```bash\npython3 scripts/agent_learning.py hook-review-skills \\\n  --skills-dir \"${HOME}/.agents/skills\"\n```\n\nInstall the hook only after explicitly choosing to attach learning capture to\nreview skills:\n\n```bash\npython3 scripts/agent_learning.py hook-review-skills \\\n  --skills-dir \"${HOME}/.agents/skills\" \\\n  --apply\n```\n\nWhen a review skill has a separate repository source, also pass that repository\nskill directory:\n\n```bash\npython3 scripts/agent_learning.py hook-review-skills \\\n  --skills-dir \"${HOME}/.agents/skills\" \\\n  --repo-skills-dir \"/path/to/repository/skills\" \\\n  --apply\n```\n\nThe command detects review skills from their frontmatter and early workflow\ntext. It skips `record-agent-learning` and `consolidate-agent-learnings`, avoids\nduplicate hooks, updates the installed local copy, and updates a matching\nrepository source when `--repo-skills-dir` is provided.\n\nThis hooked-review flow starts only from an explicit hook-mode request and then\nchanges future review workflows.\n\n```mermaid\nflowchart LR\n  accTitle: Hooked review skill flow\n  accDescr: Shows how record-agent-learning hooks review skills and captures future lessons.\n  request[\"User requests hook mode\"] --\u003e hook[\"Run hook-review-skills --apply\"]\n  hook --\u003e scan[\"Scan local skill directory\"]\n  scan --\u003e detect{\"Review skill detected?\"}\n  detect --\u003e|No| skip[\"Skip skill\"]\n  detect --\u003e|Yes| append[\"Append Agent Learning Hook\"]\n  append --\u003e future[\"Future review skill run\"]\n  future --\u003e lesson{\"Reusable lesson produced?\"}\n  lesson --\u003e|No| no_capture[\"Skip capture\"]\n  lesson --\u003e|Yes| capture[\"Run record-agent-learning\"]\n  capture --\u003e inbox[\"Write Obsidian inbox note\"]\n```\n\n## Automations\n\nThe active Codex automations should use the prompt files under `automations/`:\n\n- `agent-learning-midnight-consolidation` at `00:00` Europe/Rome;\n- `agent-learning-morning-review-email` at `08:30` Europe/Rome;\n- `agent-learning-noon-consolidation` at `12:00` Europe/Rome.\n\nThese automations are stored under `~/.codex/automations/` after Codex creates\nthem. The shell installer also writes these records directly so a normal\n`./install.sh` run activates the daily loop without a separate manual Codex\nstep.\n\nThis automation flow follows the prompt files in `automations/` and the\nnotification behavior in `scripts/agent_learning.py notify`.\n\n```mermaid\nflowchart LR\n  accTitle: Scheduled automation flow\n  accDescr: Shows consolidation and review email automation paths.\n  midnight[\"00:00 consolidation\"] --\u003e consolidate[\"Process inbox and reviews\"]\n  noon[\"12:00 consolidation\"] --\u003e consolidate\n  consolidate --\u003e promote[\"Promote safe lessons\"]\n  promote --\u003e report[\"Write report and validate\"]\n  morning[\"08:30 review email\"] --\u003e pending{\"Pending reviews?\"}\n  pending --\u003e|No| quiet[\"Do not send email\"]\n  pending --\u003e|Yes| gmail{\"Gmail connector available?\"}\n  gmail --\u003e|Yes| send_gmail[\"Send concise review email\"]\n  gmail --\u003e|No| send_msmtp[\"Use notify --send-msmtp\"]\n```\n\nThe email automation tries the Gmail connector first. If it is unavailable, it\nuses the local `msmtp` fallback through `scripts/agent_learning.py notify`.\n\n## Validation\n\nRun:\n\n```bash\nmarkdownlint --config ~/.markdownlint.json AGENTS.md CHANGELOG.md README.md skills/**/*.md automations/*.md\nshellcheck --enable=all install.sh\npython3 -m py_compile scripts/agent_learning.py tests/test_agent_learning.py\npython3 -m unittest discover -s tests\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcomc%2Fagent-learning-system","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcomc%2Fagent-learning-system","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcomc%2Fagent-learning-system/lists"}