Where Should Your Context Live?

Working with AI coding agents frequently exposes session memory limits. When a new session opens, previously established architectural choices, naming conventions, and technical constraints are lost.

Resolving this requires structured, persistent context storage.

Determining where context should live depends on team topology, repository architecture, and the frequency of change.

Three distinct patterns have emerged across production workflows.

Three context storage approaches

1. Integrated in your code repo

In this model, context files (CLAUDE.md, architectural decision records, convention documents) live directly within the application repository alongside source code.

How it works in practice: Teams create structured markdown files in the repository root or a dedicated docs/ directory. AI agents ingest these files upon initialization. When conventions evolve, documentation updates accompany the pull request containing the code changes.

Strengths:

Context remains strictly versioned alongside the code it describes. Checking out a historical branch preserves the corresponding documentation.
Pull requests provide an established review and attribution mechanism for documentation updates.
Developer onboarding is immediate: cloning the repository supplies all agent configuration requirements.
Uses existing version control infrastructure without additional tooling overhead.

Limitations:

Cross-repository conventions require manual duplication across multiple services, increasing drift risk.
Focuses heavily on technical constraints, making high-level product strategy or qualitative customer research awkward to store.
In larger engineering organizations, shared configuration files can create frequent merge conflicts.

Best fit: Small to mid-size engineering teams operating on a single product or within a monorepo.

2. Separate context repository

This approach decouples documentation from specific codebases, maintaining a dedicated central repository that agents reference across multiple projects.

How it works in practice: A standalone Git repository holds design principles, shared API standards, data schemas, and architecture records. AI agents pull from or mount this repository during execution.

Strengths:

Cross-cutting standards (design tokens, security protocols, API guidelines) maintain a single authoritative source.
Enables broader collaboration: designers, product managers, and technical writers contribute directly without touching production application repositories.
Scales across polyglot architectures and multi-repository microservices.
Allows context documentation to evolve on an independent release cycle.

Limitations:

Risk of documentation drift if central standards are not synchronized with active codebase refactors.
Introduces multi-repository coordination overhead for small teams.
Requires explicit discovery mechanisms so team members and agent configurations locate the central repository.
Requires CI/CD tooling to fetch and mount the external repository into local agent environments.

Best fit: Mid-size to large organizations with distributed repositories and shared architectural standards.

3. Markdown files in a knowledge management tool

This model relies on a personal or team knowledge base (such as Obsidian or a synchronized markdown folder) accessed via file system mounts or MCP servers.

How it works in practice: Contributors maintain a structured knowledge graph linking strategic intent, user research findings, competitive intelligence, and technical constraints. Agents query this broader knowledge base rather than narrow repository instructions.

Strengths:

Captures rich, multi-dimensional context spanning product strategy, customer feedback, and business rules.
Integrates with daily note-taking workflows, producing documentation as a natural byproduct of discovery and planning.
Bidirectional linking surfaces unexpected connections between domain entities and architectural decisions.
Provides a tailored personal advantage for solo builders and independent consultants.

Limitations:

Scaling collaborative editing across large teams requires rigorous vault structure and governance.
Tooling integrations (MCP servers, sync protocols) can experience local network or file lock interruptions.
Lacks formal Git-based diff review and automated approval workflows.
Version history is often unmanaged, making point-in-time audits difficult.

Best fit: Solo practitioners, consultants, and individual contributors augmenting team workflows with personal domain knowledge.

Tradeoffs for each approach

The architectural model: a tiered stack

The most effective architecture combines these approaches into a tiered stack based on organizational scale.

Context stack recommendation by team size

For solo builders and independent consultants: Use a structured personal knowledge base for strategic decisions, product research, and domain models. Supplement with in-repo CLAUDE.md files for repository-specific execution rules.

For small teams (2 to 5 people): Rely on in-repo markdown files (CLAUDE.md, ADRs, convention docs) versioned alongside application code. Supplement with a shared lightweight repository for organization-wide standards.

For mid-size teams (5 to 20 people): Deploy all three tiers: a central repository for cross-cutting standards, in-repo documentation for project-specific rules, and individual knowledge bases for personal practitioner workflows.

For enterprise organizations: Establish formal governance around central context repositories, including designated owners, scheduled audit cadences, and CI-based documentation linting.

The underlying principle

Context that is not maintained degrades agent accuracy.

An outdated configuration file or stale architecture document actively misguides AI agents, generating confident errors.

Select storage mechanisms where maintaining documentation aligns naturally with the rhythm of daily development.

Context density forms the core operational advantage for AI-assisted engineering teams.

This is Part 2 of the Context Engineering series. Continue with Part 3: Not All Context Changes at the Same Speed or revisit Part 1: Context Is the New Competitive Advantage.

References: Martin Fowler (Architectural Decision Records), Swyx (Context Engineering for Codebases), Linear Documentation Standards.