Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion src/docs/Frameworks/Agentic-Development/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -258,7 +258,7 @@ Different clients load different files, but the framework keeps the same depende
## Adoption path

1. Create or identify the organization `docs` repository.
2. Create or identify the organization `memory` repository.
2. Create or identify the organization `memory` repository, using the [Memory Repository Template](memory-template.md) as the starting scaffold.
3. Add `docs/index.md` and `memory/index.md` as the two root maps.
4. Add framework docs, standards, and agent role descriptions to `docs`.
5. Add starter memory sections to `memory`.
Expand All @@ -269,6 +269,7 @@ Different clients load different files, but the framework keeps the same depende
## Where this connects

- [Spec](spec.md) β€” the requirements this design delivers.
- [Memory Repository Template](memory-template.md) β€” the concrete scaffold every organization's canonical `memory` repository instantiates.
- [Agentic Development](../../Ways-of-Working/Agentic-Development.md) β€” the way-of-working standard this framework implements.
- [Documentation Model](../../Ways-of-Working/Documentation-Model.md) β€” why spec and design are split.
- [README-Driven Context](../../Ways-of-Working/Readme-Driven-Context.md) β€” why local repository context remains the front door.
1 change: 1 addition & 0 deletions src/docs/Frameworks/Agentic-Development/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,5 +15,6 @@ A repository adopts the framework by carrying thin agent pointer files and by le
| --- | --- |
| [Spec](spec.md) | Requirements for the agentic development framework β€” org-scoped documentation, memory, and pointer files that make agents behave correctly per project. |
| [Design](design.md) | How the agentic development framework is built β€” OKF documentation, org memory, thin repo pointers, and deterministic context resolution. |
| [Memory Repository Template](memory-template.md) | The concrete, copy-pasteable scaffold every organization's memory repository instantiates, and why it deliberately breaks from the Repository Standard. |

<!-- INDEX:END -->
92 changes: 92 additions & 0 deletions src/docs/Frameworks/Agentic-Development/memory-template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
---
title: Memory Repository Template
description: The concrete, copy-pasteable scaffold every organization's memory repository instantiates, and why it deliberately breaks from the Repository Standard.
---

# Memory Repository Template

[Spec](spec.md) and [Design](design.md) require every adopting organization to have a
`memory` repository, and the design's [organization anatomy](design.md#organization-anatomy)
already names `MSXOrg/memory` and `PSModule/memory` as canonical examples. Neither design
document defines an exact file layout β€” this page is that layout. It is the one scaffold
every adopting organization's `memory` repository instantiates. Content differs per
organization; structure does not.

## Scaffold

```text
memory/
β”œβ”€β”€ README.md # front door: what this repo is, that it's private, "commit straight to main, no PR"
β”œβ”€β”€ CONTRIBUTING.md # short: direct push to main, no PR/review gate, keep entries short/dated/factual
β”œβ”€β”€ .gitattributes
β”œβ”€β”€ .gitignore
β”œβ”€β”€ index.md # OKF root index (okf_version frontmatter), links to the sections below
β”œβ”€β”€ gotchas/ # short, dated entries: pitfalls, conventions, verified commands
β”‚ └── index.md
β”œβ”€β”€ knowledge/ # durable facts about the ecosystem, tools, cross-repo relationships
β”‚ β”œβ”€β”€ index.md
β”‚ └── repos/ # one file per repo worth remembering repo-specific facts about (created lazily as needed)
└── agents/ # per-agent-role working knowledge; empty stub until agent roles are formally defined
└── index.md
```

Create `knowledge/repos/<repo>.md` files lazily, only once a repository accumulates facts
worth remembering β€” the folder starts empty in a freshly scaffolded `memory` repository.

## How the scaffold maps to what memory owns

[Design](design.md#memory) already states what the `memory` repository owns. Each
top-level folder is one of those responsibilities made concrete:

| Folder | Owns (from [Design](design.md#memory)) |
| --- | --- |
| `gotchas/` | Recurring gotchas and lessons learned. |
| `knowledge/` | Active project context that should survive a single chat session, project-specific preferences that are factual rather than private user preference, and issue/PR/incident notes worth reusing. |
| `agents/` | Agent role working knowledge. |

`index.md` is the root map described in [Design's indexes section](design.md#indexes-as-the-mindmap):
it links to `gotchas/index.md`, `knowledge/index.md`, and `agents/index.md` so a human or
agent can start at the root and drill inward.

## A deliberate exception to the Repository Standard

[Repository Standard](../../Ways-of-Working/Repository-Standard.md) lists the files every
repository must carry: `LICENSE`, `SECURITY.md`, `SUPPORT.md`, `CODE_OF_CONDUCT.md`,
`.github/dependabot.yml`, `.github/CODEOWNERS`, `.github/pull_request_template.md`, and
more. A `memory` repository intentionally omits all of these.
[Organization Standard](../../Ways-of-Working/Organization-Standard.md) allows an
initiative to define type-specific exceptions to the default file set β€” this is that
exception, made explicit rather than left as an oversight:

- **Private, not public.** There is no external audience to license, and no public
vulnerability surface to run a `SECURITY.md` disclosure process against.
- **No PR workflow.** [Spec](spec.md#requirements) allows memory changes to be
lighter-weight than `docs` changes, as long as they stay versioned in git. A
`pull_request_template.md` and `CODEOWNERS` review routing make no sense for a repo
where every change lands as a direct commit to `main`.
See [Memory writing rules](design.md#memory-writing-rules) for what a good direct
commit looks like.
- **No external dependencies.** Plain Markdown files have no supply chain, so
`.github/dependabot.yml` has nothing to update.
- **Small, defined audience.** `SUPPORT.md` and `CODE_OF_CONDUCT.md` exist to set
expectations for a broad or public contributor community; a `memory` repository's
audience is the organization's own humans and agents.

A `memory` repository still carries `README.md`, `CONTRIBUTING.md`, `.gitattributes`, and
`.gitignore` β€” the minimum needed to explain itself and behave predictably in git.

## Visibility

`memory` repositories default to **private**. Working memory can capture internal
context, half-finished reasoning, and organization-specific detail that isn't meant for a
public audience, even when the adjoining `docs` repository is public.

## Where this connects

- [Spec](spec.md) β€” the requirement that every organization has a `memory` repository.
- [Design](design.md) β€” the organization anatomy, `memory` repository role, and OKF page
model this scaffold implements.
- [Repository Standard](../../Ways-of-Working/Repository-Standard.md) β€” the default file
set this page's scaffold deliberately departs from.
- [Organization Standard](../../Ways-of-Working/Organization-Standard.md) β€” how
initiative-defined, type-specific exceptions to the default file set are allowed.
1 change: 1 addition & 0 deletions src/docs/Frameworks/Agentic-Development/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,7 @@ A lower layer MAY refine a higher layer, but MUST NOT contradict it unless the h
## Where this connects

- [Design](design.md) β€” how these requirements are delivered.
- [Memory Repository Template](memory-template.md) β€” the concrete scaffold every organization's canonical `memory` repository instantiates.
- [Agentic Development](../../Ways-of-Working/Agentic-Development.md) β€” the existing way-of-working standard this framework operationalizes.
- [Documentation Model](../../Ways-of-Working/Documentation-Model.md) β€” how specs and designs are written and kept evergreen.
- [Open Knowledge Format](../../Dictionary/index.md#open-knowledge-format) β€” the Markdown and frontmatter model used for knowledge pages.
1 change: 1 addition & 0 deletions src/zensical.toml
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,7 @@ nav = [
"Frameworks/Agentic-Development/index.md",
{"Spec" = "Frameworks/Agentic-Development/spec.md"},
{"Design" = "Frameworks/Agentic-Development/design.md"},
{"Memory Repository Template" = "Frameworks/Agentic-Development/memory-template.md"},
]},
{"Process-PSModule" = [
"Frameworks/Process-PSModule/index.md",
Expand Down